[U-Boot] "make htmldocs" gives error

[U-Boot] "make htmldocs" gives error

[Abraham V.]

Hello everyone,
(cc Simon Glass)

I just tried to make the documentation for uboot with the following
command (checked out latest mainline sources);

> make htmldocs
cc     tools/kernel-doc/docproc.c   -o tools/kernel-doc/docproc
make U_BOOT_VERSION=2014.01-rc1 -C doc/DocBook/ htmldocs
make[1]: Entering directory `/home/abraham/SPACE/docs_uboot/doc/DocBook'
xmlto html -m /home/abraham/SPACE/docs_uboot/doc/DocBook/stylesheet.xsl
--skip-validation -o /home/abraham/SPACE/docs_uboot/doc/DocBook/fs
/home/abraham/SPACE/docs_uboot/doc/DocBook/fs.xml && echo '<a
HREF="fs/index.html"> fs</a><p>' >
/home/abraham/SPACE/docs_uboot/doc/DocBook/fs.html
Input file /home/abraham/SPACE/docs_uboot/doc/DocBook/fs.xml not found
make[1]: *** [/home/abraham/SPACE/docs_uboot/doc/DocBook/fs.html] Error 1
make[1]: Leaving directory `/home/abraham/SPACE/docs_uboot/doc/DocBook'
make: *** [htmldocs] Error 2
>

The logs in doc/Docbook/Makefile indicate that it was Simon's commit
which is causing this problem (at least, he's the one who added in the
fs.xml dependency without committing said file). But even if I remove
this from the Makefile;

> make htmldocs
make U_BOOT_VERSION=2014.01-rc1 -C doc/DocBook/ htmldocs
make[1]: Entering directory `/home/abraham/SPACE/docs_uboot/doc/DocBook'
/home/abraham/SPACE/docs_uboot/tools/kernel-doc/docproc doc
/home/abraham/SPACE/docs_uboot/doc/DocBook/linker_lists.tmpl
>/home/abraham/SPACE/docs_uboot/doc/DocBook/linker_lists.xml
Error(/home/abraham/SPACE/docs_uboot/include/linker_lists.h:101):
cannot understand prototype: '__LINKER_LISTS_H__ '
Error(/home/abraham/SPACE/docs_uboot/include/linker_lists.h:165):
cannot understand prototype: '/**  * ll_entry_start() - Point to first
entry of linker-generated array  * @_type: Data type of the entry  *
@_list: Name of the list in which this entry is placed  *  * This
function returns (_type *) pointer to the very first entry of a  *
linker-generated array placed into subsection of .u_boot_list section
* specified by _list argument.  *  * Since this macro defines an array
start symbol, its leftmost index  * must be 2 and its rightmost index
must be 1.  *  * Example:  * struct my_sub_cmd *msc =
ll_entry_start(struct my_sub_cmd, cmd_sub); '
make[1]: *** [/home/abraham/SPACE/docs_uboot/doc/DocBook/linker_lists.xml]
Error 2
make[1]: Leaving directory `/home/abraham/SPACE/docs_uboot/doc/DocBook'
make: *** [htmldocs] Error 2
>

We can see that there's some issue with parsing the comments in the
linker_lists.h header file.

I can understand general developer reluctance at updating
documentation (I'm lazy about it too), but do we have any way to
generate some kind of documentation for u-boot? Even Linux-style man
pages will do.

Or is my only recourse to just refer all the doc/README.* files one at a time?

-Abraham Varricatt

[U-Boot] "make htmldocs" gives error

[Masahiro Yamada]

Hello Abraham,


On Tue, 3 Dec 2013 14:25:44 +0530
"Abraham V." <abraham.varricatt@vvdntech.com> wrote:

> Hello everyone,
> (cc Simon Glass)
> 
> I just tried to make the documentation for uboot with the following
> command (checked out latest mainline sources);
> 
> [snip]
> We can see that there's some issue with parsing the comments in the
> linker_lists.h header file.

I posted patches to fix this issue.

> I can understand general developer reluctance at updating
> documentation (I'm lazy about it too), but do we have any way to
> generate some kind of documentation for u-boot? Even Linux-style man
> pages will do.

You may get disappointed because there are only two documents
under doc/Docbook/.
Anyway, we can do "make pdfdocs" if my patches are applied.

> Or is my only recourse to just refer all the doc/README.* files one at a time?

I think
 - doc/README.*
 - web page (http://www.denx.de/wiki/U-Boot/Documentation)
are more recommended.



Best Regards
Masahiro Yamada