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

[Albert ARIBAUD]

Hi Marek,

On Fri, 5 Oct 2012 02:28:19 +0200, Marek Vasut <marex at denx.de> wrote:

> 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.

Good point. Actually, environment variables (or an overridable
configuration file) may help alleviate all three points above, avoid
if/then/else (yes, I understand Linux people may not like that)...

> Best regards,
> Marek Vasut

Amicalement,
-- 
Albert.