[U-Boot] [PATCH 1/4 V2] doc: kerneldoc: Implant DocBook from Linux kernel

[Marek Vasut]

Dear Albert ARIBAUD,

> Hi Marek,
> 
> Comments based on the assumption that we want to sync with the Linux
> tools.
> 
> General comment/hypothetical question: would it not be simpler to patch
> the existing Linux tools in-place so that we can use them on the U-Boot
> tree?

Yes, it is a good idea. I'll do that. The problem is, replies to my patches do 
documentation mailing lists are slow, that's for one thing.

The other, much more grave and unpleasant is that we're way too far behind the 
DM schedule. I don't know what to do, but since pushing stuff upstream goes much 
slower than I expected, I will soon be left with no option other than forking u-
boot, finishing the university project and -- at the end, without the team -- 
merge the stuff slowly back upstream.

The patchsets are starting to depend one on another, so nothing gets in without 
something else etc ...

> Detailed comments below in this spirit; ignore if suggestion above is
> stupid/complicated/plain wrong/other(specify...or not).
> 
> On Sat, 29 Sep 2012 04:43:04 +0200, Marek Vasut <marex at denx.de> wrote:
> > Pull slightly modified version of Documentation/DocBook, the related perl
> > script scripts/kernel-doc and the scripts/docproc.c from Linux kernel and
> > implant it into U-Boot. This will allow smooth generation of kerneldoc
> > style documentation.
> > 
> > It was necessary to modify the DocBook/Makefile to work with U-Boot build
> > system. The changes were only minor though and involved replacing the
> > kbuild specific parts.
> 
> Is it possible to make replace these changes with an if/then/else
> conditional based on an external option? That would make it possible to
> try and backmerge them into the Linux version of kerneldoc.

Yes, it would ... while I already see how Linux people would hate it.

> > It was also necessary to replace use of variables like KERNEL_VERSION
> > with U_BOOT_VERSION, strings like Linux kernel with U-Boot Bootloader
> > etc. so the generated result actually matches.
> 
> Maybe make this change more general, i.e. replace KERNEL_VERSION with
> PROJECT_VERSION with a default value assuming Linux, make magic
> constant strings variables with a linux-friendly default, and make all
> those variables overridable from command line? We'd just have to have a
> small script to provide the U-Boot-sensible values.

Yes, this would be easy. But see above.

> > Finally, it was necessary to adjust docproc.c, since the documentation in
> > U-Boot is located in doc/DocBook instead of Documentation/DocBook as is
> > in case of the Linux kernel.
> 
> Does it not make sense to drop the change above and instead, symlink
> doc/ to Documentation/? We could keep the symlink for one release then
> switch to a true rename for the release after.

I'd hate to do so ... is there any reason? An environment variable would be much 
easier, docproc already uses them a bit.

> Amicalement,

Best regards,
Marek Vasut