Re: [Boost-docs] [quickbook] Processing names with more than one underscore ( _ )

Subject: Re: [Boost-docs] [quickbook] Processing names with more than one underscore ( _ )
From: Eric Niebler (eric_at_[hidden])
Date: 2011-02-15 05:30:53

On 2/15/2011 7:05 AM, Edward Diener wrote:
> On 2/14/2011 6:34 PM, Daniel James wrote:
>> Well, quickbook is a tool for generating a dialect of docbook. The
>> whole idea of docbook is to generate documentation based on
>> semantically marked up text. In this example, everything which is code
>> should be marked up as code.

Right.

> So you are saying that whenever I mention any identifier which refers to
> names in my code it should be marked using the backtick to surround it.
> Fair enough I will do that from now on.

<nod> If you do this, the resulting docs will also be easier to read
because identifiers will appear in code font.

IIRC, the original version of quickbook that I wrote (actually ported
from Joel's quickdoc) didn't have the shortcut notation for bold,
italics, underline, etc. Joel added it later as a convenience. I never
particularly cared for it, for just the reasons Edward describes: it's
not quickbook-ish, it doesn't nest cleanly, and it sometimes catches you
unawares, forcing you to examine the output carefully to catch mistakes.
I wouldn't be opposed to a switch that disabled it, or at least warned.
(I'd like to rip it out, but we can't now.) Daniel, it wouldn't be
creating a new dialect since one would be a proper subset of the other.

Besides, I think there must be a bug in the handling of shortcut
notation. This:

  some_ident_ifier

should not put "ident" in italics, but IIRC it does. The shortcut
notation should only kick in when the it is surrounded by whitespace, right?

-- 
Eric Niebler
BoostPro Computing
http://www.boostpro.com