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-15 00:05:52

On 2/14/2011 6:34 PM, Daniel James wrote:
> On 13 February 2011 19:48, Edward Diener<eldiener_at_[hidden]>  wrote:
>> On 2/13/2011 1:24 PM, Daniel James wrote:
>>>
>>>
>>> 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.
>>
> [snip]
>>
>> 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.
>
> 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.

> If it is then there's no issue here since
> underlines don't have to be escaped in code. To use quickbook
> effectively, you really have to be willing to do things like that.

OK, I will. I had really thought that names in code, marked up as code 
with the backticks, were meant to be used only when I was actually 
referring to some line of code itself, and not casually just because 
some identifier was a name used in the code of my library.

>
> But you find this an unacceptable burden, which suggests to me that
> quickbook just isn't for you. You'll always be fighting it because
> you're opposed to the whole philosophy. It's like someone who believes
> that programming languages should be dynamically typed using an
> explicitly typed language - a constant source of frustration.

I honestly do not think that objecting to the way a quickbook 
redundancy, which you have to admit the "Simple markup for formatting" 
is since it can all be done in another less intrusive way, causes 
problems when entering perfectly normal text for Boost C++ programmers 
in a quickbook document, is being "opposed to the whole philosophy."

But I also have a feeling from that comment that the "Simple markup for 
formatting" is the way Docbook accepts text and is not Quickbook 
specific. If that is the case I can understand why you think the way you 
do about my suggestion, since I agree that attempting to change the way 
Docbook operates is impossible. But if it is purely a Quickbook 
convention I do not understand why you think my suggestion is so bad, 
even if you disagree with it.