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

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

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 '''⌉''']

and as templates

[template Alpha[]'''Α'''] [/ ? Greek capital letter alpha]  // in
html4_symbols. qbk

but one could also use

[def __Alpha '''Α''']

[template alpha[]'''Α''']

"The empty brackets after the template identifier (alpha[]) indicates no
arguments. If the template body does not look like a template argument list,
we can elide the empty brackets."

So we can write just [alpha]  or __alpha

Obviously there is a case for templates when a parameter is involved, for
example: 

[template super[x]'''<superscript>'''[x]'''</superscript>''']

[template ceil[x] '''&#x2308;'''[x]'''&#x2309;''']

But it seems more consistent to use templates for both?

(I vaguely remember having to use [space] but perhaps that has disappeared?)

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.
    * 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.
"

My instinct is to use templates - though missing the closing ] has caused me
grief ;-)

Are there other issues that I am not aware of?

Recommendations?

Paul

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