Re: [docbook-apps] <sbr/> treatment in <cmdsynopsis>

[Michael Smith <smith@xml-doc.org>]

Roman Neuhauser <neuhauser@chello.cz> writes:

>     So, do I need to file a PR at the sf.net site or do the maintainers
>     read this list? And when can I expect the fix to appear in a
>     release?

If you want an official release, it'll be in in 1.68.1, which will
go out within the next two weeks.

The tracker is set up such that manpages bugs get auto-assigned to
me. I should be able to check in the fix today. After I do that, a
snapshot will automatically get built, and you will be able grab
it from here:

  http://docbook.sourceforge.net/snapshots/

Check the LatestChanges log there. If I've checked it in, it'll be
listed there and the latest snapshot will include the fix.

>     Also, the output of the stylesheet looks very inferior to that of
>     man pages written by hand (excessive or missing whitespace, other
>     bugs); how fast are reported bugs usually fixed? Is the man page
>     stylesheet actively maintained? Widely used (I know only FreeBSD in
>     this regard, and that system has man pages written "by hand")?

I am the current maintainer for the manpages stylesheet stuff.
They weren't being actively maintained when I took over work on
them, and they have not actually been maintained since. I have
been planning to fix some of the more egregous problems (the
too-much whitespace thing, for one) and add some new features, but
despite good intentions, have not had much time. Maybe this month.

I use the manpages stylesheets and have a post-processing script
set up to clean up the problems. It basically just does a bunch of
regex search-and-replacing to add and remove newlines where
needed. It works great. For me. But does nobody else any good.
Produces quality output -- final output seems to me to  as good as
anything written manually in groff.

So I just need to go back and look at what my script is doing, and
then roll those changes back into the stylesheets. Should have
done it in XSLT to begin with, but at the time I set it up, I was
in a hurry to get it done and just figured it would be quicker to
do it using a shell script.

For now, if you want to try the post-processing approach, I can
try to extract it from the makefile I have it in and put it online
somewhere (there is a bunch of other stuff in the makefile that's
related to the specific project I made it for and that you won't
have any need for).

Anyway, I will try to get some stylesheet changes checked in over
the next couple of weeks. But if you need it quicker than that
anand have XSLT chops and are willing to put some time into
working on the stylesheets, I can add you to the project as a
developer and you can make the fixes yourself :)

>     Many questions from a newcomer, I know, but I would like to make
>     a qualified decision whether I should kick the docbook source any
>     further or just write the documentation with mdoc(7).

Stick with DocBook, brother. You'll be a lot happier in the long
run. I think the current limitations in the stylesheets are
fixable, and in the mean time, you can definitely get around them
by setting up some automated post-processing cleanup.

  --Mike

smime.p7s