Re: [docbook-apps] [PATCH] make funcsysopsisinfo verbatim in manpages

["Michael(tm) Smith" <smith@sideshowbarker.net>]

Joe Orton <jorton@redhat.com> writes:

> Mike, thanks a lot for the fix, it works fine.  Would you accept a patch 
> to add a parameter to control whether the funcsynsopsis as a whole is 
> bold-ified?

I will very gladly accept patches for anything. :-)

But as far as Funcsynsopsis in particular, after spending some
more time thinking about , I realized:

  - why the man(7) man page mentions the ".BI" (bold alternating
    with italics) request is "especially useful for function
    specifications" (because it's a PITA doing it otherwise)

  - that it'd probably be a lot cleaner and easier just to use
    that .BI request instead of doing it the (kludgey and
    overcomplicated) way I had the manpages stylesheet doing it

So I just checked in a change that switches to that instead.

And that change makes it much easier to implement support for
controlling whether the funcsynsopsis as a whole is bold-ified.
All the code needs to do now is just replace the name of one
roff request in order to flip the bold formatting off.

There are two new params for controlling it:

  man.funcprototype.font
    "BI" by default, for bold with Parameter output in italic;
    switch to "RI" to get un-bold (roman) with italics for
    Parameter (or plain "R" if you don't want italic params)

  man.funcsynopsisinfo.font
    "B" by default; change to "R" for un-bold

Not sure if that's the same sort of thing as what you had in mind
to submit as a patch, but it seems like the easiest and cleanest
way to implement it. It also brings the actual roff output more in
line with what's used in the roff markup in the source for most
existing "function" (man2/man3) man pages.

Anyway, please test with the latest snapshot and let me know if it
breaks anything or if you think further adjustments are needed
(patches gladly accepted).

> I think it actually looks better without, standards be damned!

I personally also think it looks a lot better without bold. But
like it no, I think we probably ought to try make sure the default
output matches the specifications (such as they are) outlined in
the man(7) page. And that bold-in-function-specifications
guideline is one thing it's pretty clear about.

> But, being inconsistent, I'm not sure I like having the indent changed 
> by default just to avoid some whitespace, the three character indent 
> itself looks rather "non-standard" - it doesn't have that authentic 70's 
> "ye olde manpage" feel to it! :)

Hehe.. well, I guess I like prefer the retro look-and-feel too.
The default-indent change was actually a sort of experiment I've
just been messing around with -- to try to free up some more space
for output of wide tables and verbatim stuff. Anyway, I think I'll
keep it as an option but probably change the default back to the
standard 8-character-wide lefthand-gutter look. I can see now that
there is actually a certain rationale being it.

> Otherwise the snapshot (I'm using the one from the 15th) is producing 
> great output for all of the pages I've checked.  I like the change to 
> turn off hyphenisation and justification by default, I've always thought 
> they were ugly.

Thanks for the feedback and please definitely let me know if you
more suggestions for changes or ideas for other features. I
recently addes support for a few more things, and greatly improved
output for the AUTHOR/AUTHORS section. Among other things, it
now picks up the Personblurb or Contrib content associated with an
an Author/Editor/Othercredit, and displays that below the names;
like this:

  AUTHORS
    Martijn van Beers <lotr@users.sourceforge.net>
      Wrote the original implementation of the DocBook XSLT manpages
      styleheets.

    Joe Orton
    Member, DocBook Project
      Contributed key features to the manpages stylesheets.

    Michael(tm) Smith <smith@sideshowbarker.net>
    Tokyo, Japan
      Wrote the documentation you're now reading.

It also handles Affiliation ("Member, DocBook Project") and
Address both outside and inside Affiliation ("Tokyo, Japan"). If
you have time to try it out a little and let me know what you
think, I would very much appreciate.

Next, back to finishing the implemention of Table support. I've
had a basic implementation for a while now, working fine for
normal tables, but not so well for those than have vertical spans
(rowspan). I think I have an clear idea now of how to fix it.
Just need to find some time to actually do it.

   --Mike

smime.p7s