Re: [Boost-docs] How best to abbreviate calls to Unicode symbols using Quickbook

Subject: Re: [Boost-docs] How best to abbreviate calls to Unicode symbols using Quickbook
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2010-09-07 13:30:18

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-
> bounces_at_[hidden]] On Behalf Of Daniel James
> Sent: Tuesday, September 07, 2010 1:19 PM
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] How best to abbreviate calls to Unicode symbols
using
> Quickbook
> 
> On 7 September 2010 12:39, Paul A. Bristow <pbristow_at_[hidden]>
> wrote:
> > Using Unicode values is a bit 'write-only', so giving a symbol a name
> > seems good but
> >
> > I've noted a mix of using Unicode symbols both as MACRO defs and as
> > templates, for example:
> >
> > [def __ceilR '''&#x2309;''']
> 
> This is preferred: [def __ceilR \u2309].
> and as templates
> >
> > [template Alpha[]'''&#x391;'''] [/ ? Greek capital letter alpha]  //
> > in html4_symbols. qbk
> 
> Or: [template Alpha[]\u0391]

OK - \\u0391 is nicer  (though it hides the hexness ;-)

(but at least you can't forget the x (and I wondered why I got a squiggle
for a space ;-)

And the Unicode tables are in hex, so that makes it easier.
 
> [snip]
> > But it seems more consistent to use templates for both?
> 
> In my opinion, there's a semantic difference between square brackets -
which
> are structural (like tags in html), and things like escapes and macros -
which are
> part of the text. But this is just my opinion, and not consistently
applied in
> quickbook.
> > QuickBook docs say
> > "
> > The difference with macros are
> >
> >    * The explicit template expansion syntax. This is an advantage
> > because, now, we don't have to use obscure naming conventions like
> > double underscores (e.g. __alpha__) to avoid unwanted macro replacement.
> 
> Yes.
> 
> >    * The template is expanded at the point where it is invoked. A
> > macro is expanded immediately at its point of declaration. This is
> > subtle and can cause a slight difference in behavior especially if you
> > refer to other macros and templates in the body.
> 
> Not really relevant in this case.
> 
> > My instinct is to use templates - though missing the closing ] has
> > caused me grief ;-)
> 
> Quickbook could handle this better, something that's on my mind.

(The template name would help - I had half the Greek alphabet to choose
from!
> 
> > Are there other issues that I am not aware of?
> 
> Of the top of my head: templates and macros have different scoping rules,
you
> can use macros in some places where you can't use templates (I forget
exactly
> where, I'll look into it later), and macros can be used for a conditional
phrase
> (i.e. include a phrase if a specific macro is defined).
> 
> The scoping rule is that macros are only defined for the file containing
the
> definition, and any files it includes, but templates are global. So you
can't define
> macros in a file and then include it (like you do in 'html4_symbols.qbk').

> This is an issue - there's a very old 'fixme' comment in the source which
suggests that
> templates should be scoped. But this would break a lot of existing
> documentation, so I haven't followed it. I have a half formed plan to deal
with it
> - there's an email about this subject that I never get round to writing.

This would seem a *killer* issue.  For html symbols, won't it be MUCH more
convenient
to be able to include html4_symbols.qbk in my_main.qbk, (or most
conveniently anywhere?),
 and then be able to use them anywhere?

my_main.qbk,
my_section1.qbk, my_section2.qbk ...

Or am I misunderstanding?  Or are you saying that if I include
html4_symbols.qbk containing macros in
my_section1.qbk, I can't use them in my_section2.qbk?

I also observed, and do again " it seems more consistent to use templates
for both nullary and multiplary (if that's the word ;-)"?

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]