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.
> 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
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
This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC