[Swan-dev] always generating the man page

[Paul Wouters]

On Fri, 8 May 2015, Andrew Cagney wrote:

> Now that I'm trying to build the man pages I'm finding that they are in a bit of a mess, for instance:
> 
> - errors (you just fixed one)
> 
> - no XML source when clearly they were generated (the generated by xmlto line at the top is a bit of a give away :-)

Some were generated back to xml from rof using some ancient tool
(doclifter or someting?(

> - xmlto annoyingly always exiting non-zero (hacked around)

Ok.

> - what I would argue are useless man pages (for instance documentation for libswan functions when libswan.a isn't installed)

sort of agree.

> It looks like we'll need to go through each directory, check for damage, and only then enable what is needed (which means there'll be a
> short period with very few man pages).

Not sure I understand this?

>       This is mostly a lot of legacy, from before the days of "man command
>       option" (eg man git branch)
> 
> Ah, everything should get a rename then.  It made the rules for building the man pages simpler and more transparent.
> 
> As pointed out by bleve on IRC, I've also change things so that, instead of using links, the 'solim stub' files that xmlto generates
> also get installed.
> 
> Consequently having both "man 8 pluto" and "man 8 ipsec pluto" work just requires a tweak to pluto.8.xml.

Good.

>       Note that I ran into another bug the other day. I build just before
>       midnight and so the i386 build happened on date X, and the x86_64 build
>       on date X+1. This causes the package to no longer be multilib clean.
>
>       It would be nice if we could either prevent/strip out the dates from the
>       generated man pages, or possibly use a date limited to the year and
>       month.
> 
> I wonder what other projects do; I believe standard convention is to hard-wire the dates, and then try to remember to update while
> editing :-/

But at this point, we'd have to all set them to a random date like
today. So I'm not sure what the value of the date really is. Perhaps
it is possible to just leave it out, or as Len said, use the date
of the source tar ball?

> To Lennard's idea, I'm not sure we can rely on modification dates.

Or the date specified in CHANGES of the release.

>       We removed xmlto because man pages were generated unconditionally on
>       every build, meaning it really slows things down when changing 1 .c file
>       and 99% of the time you are waiting on regenerated man pages.
> 
> I've got "make install-programs" working; and "swan-install" using that.

Ahh, I never use swan-install. But I could be convinced to use it.

> The real problem is that we delete OBJDIR.

But yeah, if it means rebuilding on 4 VMs, then not :)

>       But as I said, we want to ship generated man pages to help those cross
>       compiling. Although if the man page becomes a separate target, that
>       might no longer be a concern.
> 
> If all else fails "make programs install-programs" should work.  I also suspect cross build systems can now deal with xmlto.

Fair enough,

Paul