#319 man: Templates for segmentedlist

output: manpages
closed-fixed
XSL (399)
5
2006-03-25
2006-01-09
No

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.

Discussion

  • Daniel Leidert

    Daniel Leidert - 2006-03-08

    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

     
  • Michael(tm) Smith

    • assigned_to: nobody --> xmldoc
    • summary: Templates for segmentedlist --> man: Templates for segmentedlist
     
  • Michael(tm) Smith

    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...

     
  • Daniel Leidert

    Daniel Leidert - 2006-03-09

    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?

     
  • Daniel Leidert

    Daniel Leidert - 2006-03-10

    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

     
  • Michael(tm) Smith

    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/

     
  • Michael(tm) Smith

    • status: open --> pending-fixed
     
  • Michael(tm) Smith

    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.

     
  • Daniel Leidert

    Daniel Leidert - 2006-03-10

    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)?

     
  • Michael(tm) Smith

    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 smith@sideshowbarker.net

    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

     
  • SourceForge Robot

    • status: pending-fixed --> closed-fixed
     
  • SourceForge Robot

    Logged In: YES
    user_id=1312539

    This Tracker item was closed automatically by the system. It was
    previously set to a Pending status, and the original submitter
    did not respond within 14 days (the time period specified by
    the administrator of this Tracker).

     

Log in to post a comment.