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
_______________________________________________
Swan-dev mailing list
[email protected]
https://lists.libreswan.org/mailman/listinfo/swan-dev
