OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: Re: DOCBOOK-APPS: how to comment programlisting or source code


On Thu, Aug 22, 2002 at 06:50:54PM -0700, Dave Pawson wrote:
> At 10:41 22/08/2002, Bob Stayton wrote:
> 
> >Since programlisting is a verbatim block, can't you
> >just line  up your annotations manually as you write them? 
> >Maybe I'm not understanding what you are trying to do.
> >If you are doing long comments that wrap, perhaps you could
> >use callouts?
> 
> 
> Callouts are a good option.
> In html they do take a bit of tweaking, but look good.
> 
> Took me some time to imitate Norm, but this is what works 
> for me now. I could put them any position on the line.
> 
> 
> 
>    <example id="bl.ch">
>         <title>Chapter page sequence</title>
>         
>         <programlisting format="linespecific">
>  &lt;fo:page-sequence 
>        master-reference="chaps"
>           initial-page-number="1" 
>           format="1">                              <co id='pnf'/>
> 
>     &lt;fo:static-content
>       flow-name="xsl-region-before">
>      &lt;fo:block text-align="outside">               <co id='hd'/>
>        Chapter    &lt;fo:retrieve-marker 
>           retrieve-class-name="chapNum"/>          <co id='cn'/>
>     &lt;fo:leader leader-pattern="space" />
>        &lt;fo:retrieve-marker 
>           retrieve-class-name="chap"/>             <co id='ttl'/>   
>     &lt;fo:leader leader-pattern="space" />
>      Page &lt;fo:page-number font-style="normal" />   <co id='pna'/>
>      of &lt;fo:page-number-citation ref-id='end'/>    <co id='lp'/>
>   &lt;/fo:block>
>     &lt;/fo:static-content>
> 
> </programlisting>
>         <calloutlist>
>   <callout arearefs="pnf">
>             <para>The page number is formatted in Roman</para>
>           </callout>
> 
>           <callout arearefs="hd">
>             <para>this block forms the header on these pages</para>
>           </callout>
>           <callout arearefs="cn">
>             <para>The chapter number is retrieved as a marker</para>
>           </callout>
>           <callout arearefs="ttl">
>             <para>The chapter title is retrieved as a marker.</para>
>           </callout>
>           <callout arearefs="pna">
>             <para>The page number is added</para>
>           </callout>
>           <callout arearefs="lp">
>             <para>Last page number of document</para>
>           </callout>
> 
>         </calloutlist>
>       </example>

One additional refinement to Dave's example.  You
can make the links bidirectional by adding an
id to the <callout> and a linkends to the <co>:

<co id='pnf' linkends="pnf-callout" />
...
<callout arearefs="pnf" id="pnf-callout">

Then you can click on the callout bug in the code
to go to its explanatory text, and click on the 
callout label bug to go back to the code location.
At least with XSL.

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC