[Swan-dev] always generating the man page

[Paul Wouters]

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)

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)

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.

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

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

Paul