[Swan-dev] always generating the man page

[Andrew Cagney]

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 :-)

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

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

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

[also inline]

On 7 May 2015 at 15:10, Paul Wouters <paul at nohats.ca> wrote:

> On Thu, 7 May 2015, Andrew Cagney wrote:
>
>  - I've added xmlto to the list of things installed in the test VMs
>>
>
> That must have been there already because when I re-installed my VMs
> two days ago I ran into the bug of man page generations that would
> not happen without xmlto ?
>
> Note, that we should not break the build if no xmlto is found. Especialy
> to make it easier for cross compilers.
>
>  One annoying wart I've found is that some of the generated manpages get
>> an ipsec_ prefix removed only to then be put back.  During the
>> build it does:
>>   xmlto version.5.xml -> ipsec_version.5
>>   mv ipsec_version.5 version.5
>> and then in the install it does:
>>   install version.5 .../man5/ipsec_version.5
>> (technically the last is $(MANPROCPREFIX)version.5).
>>
>> Does anyone know of a good reason to not simply dump this behaviour; and
>> instead simply call man.xml files by their actual names?
>> For instance, version.5.xml would be renamed to ipsec_version.5.xml.  If
>> there really is a need to change ipsec_ to something else then
>> that can be handled during install.
>>
>
> 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.



> I don't think it matters whether "man ipsec_version" works or not, as
> long as "man ipsec version" works. This is true for all our things.
>
> Some library functions obviously have no command, so for some of that
> developers will just have to know to prefix it, eg "man ipsec_addrtoa".
> Some of those man3 pages would otherwise cause names too generic.
>
> One pet peeve of mine is that I think any daemon running that I can see
> with "ps" should have a man page, so "man pluto" should really work.
> Another important with with prefix is "man ipsec whack" (which is
> actually the same man page)
>

Agreed; see above.


> 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 :-/
To Lennard's idea, I'm not sure we can rely on modification dates.


 - continue to build/test/install on the VMs (they should have xmlto but
>> don't)
>>
>
> 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.

The real problem is that we delete OBJDIR.


>  Long long ago, before there were public repositories, everyone passed
>> source tar-balls around (and before that shell archives, and
>> before that, ...).  To make things easier to build, the convention of
>> including the generated documentation(1) and yacc(2) was
>> adopted.  As projects moved to public repositories, the convention stuck;
>> well for a short while. It didn't take long before
>> projects realized that it was far simpler and more robust(3) to only have
>> the original source code in the repo. If it was felt
>> that distributing generated files was helpful then the "make dist" target
>> can handle that.
>>
>
> 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.


Andrew
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.libreswan.org/pipermail/swan-dev/attachments/20150508/3f2f819a/attachment.html>