[ docbook-Feature Requests-1400097 ] man: Templates for segmentedlist

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

Feature Requests item #1400097, was opened at 2006-01-09 13:40
Message generated for change (Comment added) made by xmldoc
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=373750&aid=1400097&group_id=21935

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: XSL
Group: output: manpages
Status: Pending
Resolution: Fixed
Priority: 5
Submitted By: Alastair Rankine (alastair)
Assigned to: Michael Smith (xmldoc)
Summary: man: Templates for segmentedlist

Initial Comment:
Currently missing templates for outputting
segmentedlists into manpages. Ideally both table and
list formats would be supported (as per FO template)
but just a list format would be a good start.

Thanks.

----------------------------------------------------------------------

>Comment By: Michael Smith (xmldoc)
Date: 2006-03-10 19:01

Message:
Logged In: YES 
user_id=118135

Daniel,

Yes, please definitely either upload here a sample
source doc that demonstrates your test case, or e-mail
it to me directly at sm...@si...

Feel free to obfuscate the source if it is some proprietary
app or whatever that you are documenting. After I get the
source doc from you and test with it, I will probably
add some version of it to our unit-test suite so that I
can test for regressions of it later.

As far as the width, keep in mind that not all terminals
are 80 columns wide. Some are 132 and some are 65 or
whatever. The man(1) command checks for a MANWIDTH
environment variable every time it is invoked, so you
can experiment with different widths at man(1) run time
by doing this:

  MANWIDTH=50 man -l ./FirstName.1

or even just this:

  MANWIDTH=50 man ./FirstName.1

----------------------------------------------------------------------

Comment By: Daniel Leidert (dleidert)
Date: 2006-03-10 18:31

Message:
Logged In: YES 
user_id=1102637

Thanks. It works. It now also uses real cellular format, so
a cell can contain a newline (the situation, I called
impossible :)), so lines too long to not wrap at the
beginning of a line - it produces a nice table.

Just a minor limitation: Using the 'T{ T}' does not use the
available width. An example. The table begins at position
20. So a line can contain 60 characters until it will break.
But the above code produces an output, where only 40 chars
can be used. I breaks the line without any necessity. Can
you reproduce that (shall I send you a sample code to
reproduce this an a cnsole)?

----------------------------------------------------------------------

Comment By: Michael Smith (xmldoc)
Date: 2006-03-10 17:12

Message:
Logged In: YES 
user_id=118135

I just checked in a change for this. Please test with
the latest snapshot and let me know if it works as
expected.

Daniel,

Thanks for the revised patch. I used much of it as-is. I
did not use tab(;) call but instead have it outputting
the default tab separator. (There is always a possibility
that the seg content may contain semicolons, and I would
need to check for them and escape them if I used tab(;).
Also, the Seg element can contain a lot of different stuff,
not just text, so I have it outputting "T{" and "T}" around
all the Seg content. Also adjusted to output the
cell separator (tab character) only between cells and not
at the end of each row. And added Segmentedlist to the
set of elements we check for when handling "mixed block"
content (to prevent it from getting normalize-space() run
on it.

----------------------------------------------------------------------

Comment By: Michael Smith (xmldoc)
Date: 2006-03-10 17:12

Message:
Logged In: YES 
user_id=118135

A change for this issue has been added to the current codebase.
Please test the change with the latest snapshot from:

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

----------------------------------------------------------------------

Comment By: Daniel Leidert (dleidert)
Date: 2006-03-10 13:21

Message:
Logged In: YES 
user_id=1102637

A suggestion for the code including support for the segtitle
element and a possibility to suppress the output of these
row-titles:

<xsl:template match="segmentedlist">
  <xsl:text>&#10;.TS</xsl:text>
  <xsl:text>&#10;tab(;);&#10;</xsl:text>
  <xsl:for-each select=".//segtitle">
    <!-- should be maybe made variable, see tbl(1)
         so the user can choose the orientation -->
    <xsl:text>l</xsl:text>
  </xsl:for-each>
  <xsl:text>.&#10;</xsl:text>
  <!-- suppress output of titles -->
  <xsl:if test="$man.suppress.segtitle.output = 0">
    <xsl:apply-templates select=".//segtitle"
mode="table-title"/>
    <xsl:text>&#10;</xsl:text>
  </xsl:if>
  <xsl:apply-templates/>
  <xsl:text>.TE&#10;&#10;</xsl:text>
</xsl:template>

<xsl:template match="segmentedlist/segtitle" mode="table-title">
  <xsl:apply-templates mode="bold" select="."/>
  <xsl:text>;</xsl:text>
</xsl:template>

<xsl:template match="segmentedlist/seglistitem">
  <xsl:apply-templates/>
  <xsl:text>&#10;</xsl:text>
</xsl:template>

<xsl:template match="segmentedlist/seglistitem/seg">
  <xsl:apply-templates/>
  <xsl:text>;</xsl:text>
</xsl:template>

The titles are handled as bold-elements in this example
code. Maybe it would be nice, if the user could choose,
which orientation the cells should have. See my comment in
the code.

Regards, Daniel

----------------------------------------------------------------------

Comment By: Daniel Leidert (dleidert)
Date: 2006-03-09 21:16

Message:
Logged In: YES 
user_id=1102637

Just a suggestion: I did not add support for the titles,
because the output without the titles is more handy for me.
So IMHO a parameter would be nice to be able to suppress the
output of the row-titles. What do you think about this?

----------------------------------------------------------------------

Comment By: Michael Smith (xmldoc)
Date: 2006-03-09 19:09

Message:
Logged In: YES 
user_id=118135

Alastair,

Thanks for submitting this. I've personally never understood
why anybody would ever actually want to the "list of
repeated headings and elements" type of output for
segmentedlist, so I am reluctant to implement support for
it. But I do think the tabular output format is do-able
and I reckon I can get it added for the next release.

Daniel,

Thanks for the patch. Tabular output using tbl(1) markup
definitely seems to be the way to go with this. I reckon
I will probably use it (with some adjustments -- as it is
now, it doesn't handle segtitle at all, for one thing).
As far as the issue of line wrapping, that's an issue
that affects not just seglist handling. Output from some
other types of DocBook elements (programlisting, for one)
may also exceed the width of the console the user is
viewing the man page on, so it is not a problem exclusive
to seglist. I guess that Users that are on narrow-width
consoles are going to have problems viewing lots of things
correctly, not just man-page output from DocBook...

----------------------------------------------------------------------

Comment By: Daniel Leidert (dleidert)
Date: 2006-03-09 07:58

Message:
Logged In: YES 
user_id=1102637

Here a patch to provide segmented lists for manpages:

<!-- 
	print segmented lists as tables: uses less space as than
variablelist
-->

<xsl:template match="segmentedlist">
	<xsl:text>&#10;.TS</xsl:text>
	<xsl:text>&#10;tab(;);&#10;</xsl:text>
	<xsl:for-each select=".//segtitle">
		<xsl:text>l</xsl:text>
	</xsl:for-each>
	<xsl:text>.</xsl:text>
	<xsl:apply-templates/>
	<xsl:text>&#10;.TE&#10;&#10;</xsl:text>
</xsl:template>

<xsl:template match="segmentedlist/seglistitem">
	<xsl:text>&#10;</xsl:text>
	<xsl:apply-templates/>
</xsl:template>

<xsl:template match="segmentedlist/seglistitem/seg">
	<xsl:apply-templates/>
	<xsl:text>;</xsl:text>
</xsl:template>

I used this code for several manpages with tiny results. A
sample table would look like this

value1  value11  description111
value2  value22  description222

The only "problem" here is, that if a line contains more
than 80 characters, the line will wrap t the next line
beginning at position one. It is AFAIK not possible to use a
cellular format. The following example is AFAIK impossible:

value1  value11  description111
value2  value22  description222\n
                 description2222
value3  value33  description3333

Regards

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=373750&aid=1400097&group_id=21935