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

Subject: Re: [Boost-docs] [quickbook] Processing names with more than one underscore ( _ )
From: Edward Diener (eldiener_at_[hidden])
Date: 2011-02-13 19:48:13

On 2/13/2011 1:24 PM, Daniel James wrote:
> On 12 February 2011 19:51, Edward Diener<eldiener_at_[hidden]>  wrote:
>>
>> One can do whatever manipulations one wants to keep from having to escape
>> underscores in names which have the form of '_seq_' but it still does not
>> make having a simple format, which one can not turn off, easy to use.
>
> Quickbook is a markup language, so to use it effectively you have to
> mark up text. If that's a problem, then maybe it isn't the right
> solution for you.

There is already a font style for specifying underlined test, which is 
[_underline]. That is not going to bother anybody since one needs to 
surround text with [], which is a common way to mark up elements in 
quickbook.

Then you also add simple formatting to underline text, which is 
_underline_. I am not normally bothered in the least by two different 
ways to do the exactly same thing. But in this case it causes anybody 
who writes text, where the particular word has more than one underscore, 
problems.

In Boost the standardized way for dealing with all names is to separate 
the parts of names with underscores, and not with uppercase/lowercase 
letter changes since everything should be lowercase except macro names. 
So instead of writing MySimpleClass I am told that the Boost standard is 
to write my_simple_class. That's fine with me. But then quickbook tells 
me, because it insists not only on the font style for underlining being 
always in effect but also that the simple formatting style for 
underlining must always be in effect, even though they both do exactly 
the same thing, that when I write 'my_simple_class' in my document I 
must write instead 'my\_simple\_class'. And that's just one of many 
names a Boost programmer will refer to in the documentation with more 
than one underscore, because it is the Boost standard.

So I ask if the simple formatting for the underline can be turned off 
when processing a quickbook document so I do not have to use the 
backslash all over the place when documenting my library in quickbook, 
and your answer is the above.

Now who is being reasonable and who is not ?

>
>>   I am
>> merely suggesting that this simple format, which naturally causes many
>> headaches when used with names which are ubiquitous when documenting Boost
>> libraries, be turned off by some option. Is that really that hard to do for
>> quickbook ?
>
> It's not hard, but it's the wrong thing to do. Multiple dialects can
> cause all sorts of problems. The only dialect switch in quickbook is
> the version switch, and that's only there for backwards compatibility
> (and it's problematic enough - it's a bit buggy for included files).