[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: Single source documentation

From: John R. Daily <john_at_geekhavoc.com>
Date: 2003-11-14 15:21:50 CET

At (time_t)75798538< Colin Watson wrote:

> On Thu, Nov 13, 2003 at 09:33:37PM -0500, John R. Daily wrote:
> > One of the major remaining showstoppers is figuring out how to
> > prevent groff from treating an apostrophe at the beginning of a
> > line as a command sequence. groff allows that character to be
> > redefined, but there is no completely safe character to use; I'd
> > rather just turn it off entirely.
>
> The correct fix is to put \& (a zero-width space) in front of "." or "'"
> at the start of lines when you don't want those lines to be treated as
> requests.

The challenge is figuring out when a ' or . will be at the
beginning of a line, although now that I think about it I may
have a solution.

Is there any equivalent of <![CDATA[ in the roff world?

> > <!-- Ideally, variablelists would use the .TP macro, and itemized lists
> > might use .IP, but I can't get the macros to work as documented. Not sure
> > what I'm doing wrong. -->
>
> What does the groff output look like when you try? I'd be happy to
> suggest fixes.

I manually tweaked a small portion of the current output to
reflect what I'd previously done with TP; the file is attached.

Don't laugh (or cry) too hard; I'm a complete roff newbie.

> I'm somewhat inclined to suggest that the mdoc macro set would be a
> better fit to DocBook than the man macro set, too, although it might be
> more work. The traditional SysV man macros are mostly physical markup,
> while the BSD mdoc macros have quite rich semantic content.

I'll look at them. However, since I'm converting just to latin1
text for inclusion into C code, I'm inclined to stick with simple
physical markup.

> > <xsl:template match="screen|literallayout|programlisting">
> > <xsl:text>.nf
> > </xsl:text>
> > <xsl:apply-templates/><xsl:text>
> > .fi
> > </xsl:text>
> > </xsl:template>
>
> Perhaps also use a constant-width font here?
>
> .nf
> .ft CW
> ...
> .ft R
> .fi

Since this is strictly for latin1 text, it's irrelevant.

Thanks very much for the input; roff expertise is a valuable
commodity!

-John

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Received on Fri Nov 14 15:22:46 2003

This is an archived mail posted to the Subversion Dev mailing list.