[pacman-dev] Asciidoc manpages
Does anyone on the list know a lot about Asciidoc? Specifically, I noticed that our manpage generation has gotten a bit weird. Notice that every manpage generated in the pacman-git release (or in your own working tree when using --enable-asciidoc) has: * a weird Notes section at the bottom * a broken "See Also" section (looks like the macro is busted or something) In addition, the PKGBUILD example nclude in PKGBUILD.5 does not look so hot. Does anyone (Andrew, are you still around?) want to look into this and see what they can come up with to fix it? I swear we had it working for a while, so this may be related to a docbook-xsl upgrade. If you do investigate, be sure whatever changes you make keep both the HTML and the manpage format looking OK. -Dan
Dan McGee wrote:
Does anyone on the list know a lot about Asciidoc? Specifically, I noticed that our manpage generation has gotten a bit weird. Notice that every manpage generated in the pacman-git release (or in your own working tree when using --enable-asciidoc) has: * a weird Notes section at the bottom * a broken "See Also" section (looks like the macro is busted or something)
In addition, the PKGBUILD example nclude in PKGBUILD.5 does not look so hot.
Does anyone (Andrew, are you still around?) want to look into this and see what they can come up with to fix it? I swear we had it working for a while, so this may be related to a docbook-xsl upgrade. If you do investigate, be sure whatever changes you make keep both the HTML and the manpage format looking OK.
-Dan
_______________________________________________ pacman-dev mailing list pacman-dev@archlinux.org http://archlinux.org/mailman/listinfo/pacman-dev
Something's changed in the link expansion on man pages in the new version of asciidoc (8.2.3), the previous version (8.2.2) works fine. Looking at the changelog there's 2 changes that might have broken this - Added VMiklos's permalink patch for auto-generated section IDs (enabled by default by the sectids attribute). (http://www.mail-archive.com/asciidoc-discuss%40metaperl.com/msg00159.html) - The nested inline macros restriction has now been lifted, for example you can now include links and inline images inside footnotes. If I get some free time I'll dig deeper. Andrew P.S. Real world stuff is keeping me very busy at the moment so pacman/arch has dropped off my radar for the moment.
On Thu, Nov 08, 2007 at 06:57:44AM +0000, Andrew Fyfe <andrew@neptune-one.net> wrote:
- Added VMiklos's permalink patch for auto-generated section IDs (enabled by default by the sectids attribute). (http://www.mail-archive.com/asciidoc-discuss%40metaperl.com/msg00159.html)
as long as you don't use -a sectids, it can't break manpage generation - VMiklos
Miklos Vajna wrote:
On Thu, Nov 08, 2007 at 06:57:44AM +0000, Andrew Fyfe <andrew@neptune-one.net> wrote:
- Added VMiklos's permalink patch for auto-generated section IDs (enabled by default by the sectids attribute). (http://www.mail-archive.com/asciidoc-discuss%40metaperl.com/msg00159.html)
as long as you don't use -a sectids, it can't break manpage generation
- VMiklos
------------------------------------------------------------------------
_______________________________________________ pacman-dev mailing list pacman-dev@archlinux.org http://archlinux.org/mailman/listinfo/pacman-dev
Ooops I missed that small note in the brackets :) Thanks VMiklos Did little digging, the breakage/change is in now asciidoc converts from asciidoc to xml (so it's not docbook-xsl). In 8.2.2 manlink:pacman.conf[5] expands to <citerefentry><refentrytitle>pacman.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, in 8.2.3 it expands to man<ulink url="pacman.conf">5</ulink>, Andrew
On Nov 9, 2007 4:05 PM, Andrew Fyfe <andrew@neptune-one.net> wrote:
Miklos Vajna wrote:
On Thu, Nov 08, 2007 at 06:57:44AM +0000, Andrew Fyfe <andrew@neptune-one.net> wrote:
- Added VMiklos's permalink patch for auto-generated section IDs (enabled by default by the sectids attribute). (http://www.mail-archive.com/asciidoc-discuss%40metaperl.com/msg00159.html)
as long as you don't use -a sectids, it can't break manpage generation
- VMiklos
Ooops I missed that small note in the brackets :) Thanks VMiklos
Did little digging, the breakage/change is in now asciidoc converts from asciidoc to xml (so it's not docbook-xsl). In 8.2.2 manlink:pacman.conf[5] expands to
<citerefentry><refentrytitle>pacman.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
in 8.2.3 it expands to
man<ulink url="pacman.conf">5</ulink>,
Andrew
I think I finally tracked this down. <http://code.toofishes.net/gitweb.cgi?p=pacman.git;a=commit;h=b3c6bdda38f7e370e1f80f02a61f1d3f08c1b57d> -Dan
On Nov 7, 2007 10:38 PM, Dan McGee <dpmcgee@gmail.com> wrote:
Does anyone on the list know a lot about Asciidoc? Specifically, I noticed that our manpage generation has gotten a bit weird. Notice that every manpage generated in the pacman-git release (or in your own working tree when using --enable-asciidoc) has: * a weird Notes section at the bottom * a broken "See Also" section (looks like the macro is busted or something)
In addition, the PKGBUILD example nclude in PKGBUILD.5 does not look so hot.
I fixed the broken "See Also" and the PKGBUILD example problem with the following commit: <http://code.toofishes.net/gitweb.cgi?p=pacman.git;a=commit;h=f3e8343c7ed778deaa6615e4aca2cb68a6bc0053> The Notes issue is still outstanding. I've thrown up HTML versions of the manpages at <http://www.archlinux.org/~dan/pacman-git/> as well, generated after the above fixes. These are generated with the following: cd doc/; for txtfile in $(ls *.txt); do asciidoc $txtfile; done Looking at these, I see a few more issues. The linkage to other manpages is broken (should be a straightforward fix in the manlink macro) and displays wrong. We should turn the links in the "See Also" section into actual HTML links as well. -Dan
participants (3)
-
Andrew Fyfe
-
Dan McGee
-
Miklos Vajna