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: Daniel James (dnljms_at_[hidden])
Date: 2010-09-07 12:18:56

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]

[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.

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

I don't know.

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

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

Daniel