<div dir="ltr"><div><div><div><div><div>Now that I'm trying to build the man pages I'm finding that they are in a bit of a mess, for instance:<br><br></div>- errors (you just fixed one)<br><br></div>- no XML source when clearly they were generated (the generated by xmlto line at the top is a bit of a give away :-)<br><br></div>- xmlto annoyingly always exiting non-zero (hacked around)<br><br></div><div>- what I would argue are useless man pages (for instance documentation for libswan functions when libswan.a isn't installed)<br><br></div>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).<br><br></div>[also inline]<br><div><div><div><div><div><div><div><div><div><div><div class="gmail_extra"><br><div class="gmail_quote">On 7 May 2015 at 15:10, Paul Wouters <span dir="ltr"><<a href="mailto:paul@nohats.ca" target="_blank">paul@nohats.ca</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On Thu, 7 May 2015, Andrew Cagney wrote:<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
- I've added xmlto to the list of things installed in the test VMs<br>
</blockquote>
<br></span>
That must have been there already because when I re-installed my VMs<br>
two days ago I ran into the bug of man page generations that would<br>
not happen without xmlto ?<br>
<br>
Note, that we should not break the build if no xmlto is found. Especialy<br>
to make it easier for cross compilers.<span class=""><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
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<br>
build it does:<br>
xmlto version.5.xml -> ipsec_version.5<br>
mv ipsec_version.5 version.5<br>
and then in the install it does:<br>
install version.5 .../man5/ipsec_version.5<br>
(technically the last is $(MANPROCPREFIX)version.5).<br>
<br>
Does anyone know of a good reason to not simply dump this behaviour; and instead simply call man.xml files by their actual names?<br>
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<br>
that can be handled during install.<br>
</blockquote>
<br></span>
This is mostly a lot of legacy, from before the days of "man command<br>
option" (eg man git branch)<br>
<br></blockquote><div><br></div><div>Ah, everything should get a rename then. It made the rules for building the man pages simpler and more transparent.<br><br></div><div>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.<br><br>Consequently having both "man 8 pluto" and "man 8 ipsec pluto" work just requires a tweak to pluto.8.xml.<br><br></div><div> <br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
I don't think it matters whether "man ipsec_version" works or not, as<br>
long as "man ipsec version" works. This is true for all our things.<br>
<br>
Some library functions obviously have no command, so for some of that<br>
developers will just have to know to prefix it, eg "man ipsec_addrtoa".<br>
Some of those man3 pages would otherwise cause names too generic.<br>
<br>
One pet peeve of mine is that I think any daemon running that I can see<br>
with "ps" should have a man page, so "man pluto" should really work.<br>
Another important with with prefix is "man ipsec whack" (which is<br>
actually the same man page)<br></blockquote><div><br></div><div>Agreed; see above. <br><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Note that I ran into another bug the other day. I build just before<br>
midnight and so the i386 build happened on date X, and the x86_64 build<br>
on date X+1. This causes the package to no longer be multilib clean.<br>
<br>
It would be nice if we could either prevent/strip out the dates from the<br>
generated man pages, or possibly use a date limited to the year and<br>
month.<span class=""><br>
<br></span></blockquote><div><br></div><div>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 :-/<br>To Lennard's idea, I'm not sure we can rely on modification dates.<br><br><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
- continue to build/test/install on the VMs (they should have xmlto but don't)<br>
</blockquote>
<br></span>
We removed xmlto because man pages were generated unconditionally on<br>
every build, meaning it really slows things down when changing 1 .c file<br>
and 99% of the time you are waiting on regenerated man pages.<span class=""><br></span></blockquote><div><br></div><div>I've got "make install-programs" working; and "swan-install" using that.<br><br></div><div>The real problem is that we delete OBJDIR.<br><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Long long ago, before there were public repositories, everyone passed source tar-balls around (and before that shell archives, and<br>
before that, ...). To make things easier to build, the convention of including the generated documentation(1) and yacc(2) was<br>
adopted. As projects moved to public repositories, the convention stuck; well for a short while. It didn't take long before<br>
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<br>
that distributing generated files was helpful then the "make dist" target can handle that.<br>
</blockquote>
<br></span>
But as I said, we want to ship generated man pages to help those cross<br>
compiling. Although if the man page becomes a separate target, that<br>
might no longer be a concern.<span class="HOEnZb"><font color="#888888"><br></font></span></blockquote><div><br></div><div>If all else fails "make programs install-programs" should work. I also suspect cross build systems can now deal with xmlto.</div><div><br><br></div><div><font color="#888888">Andrew</font></div></div><br></div></div></div></div></div></div></div></div></div></div></div></div>