Scoped Macros

[Joel de Guzman]

This may be relevant to the current plan to scope macros and templates. Excerpt follows:

---

Subject: scoped macros From: "troy d. straszheim" <troy@…> Date: Sun, 6 Nov 2005 09:19:03 -0500 Newsgroups: gmane.comp.lib.boost.documentation

Hey,

I'm hooked on quickbook. I'm wondering what people think of taking the scoping out of include_action::operator() in actions.cpp, or providing some way to turn it off.

The use case is this. My docs have become very big, building them takes prohibitively long, and so I've broken them up into several chapters, one-per-file. There is a toplevel doc (book) that xincludes the docbook generated by each chapter. I use lots of little macros that look like this:

[def *something [link something /something/]]

So that at the most-important-point-of-documenation for "something", i put a

#something [section The docs for something] ..

and then wherever I'm typing along, I can always just say "For more info see *something". And "something" is produced, italicized and linked. I can change the appearance of those links in one place, and #something is easy to search for when I need to change the definition. I'm finding this *very* helpful with keeping information from getting fragmented. I have my macros in a header file macros.qbk, and [include] them in each chapter (and you can generate an index from them). Another problem this addresses is with [link]: doing

[link to.the_autogenerated_name.of.the.section link text]

can get untypably long, and if you later rearrange the structure of your docs, all the links break.

Thoughts? Thanks for a cool tool...

-t

Subject: Re: Re: scoped macros From: "troy d. straszheim" <troy@…> Date: Sun, 6 Nov 2005 12:44:06 -0500 Newsgroups: gmane.comp.lib.boost.documentation

On Sun, Nov 06, 2005 at 11:14:18PM +0800, Joel de Guzman wrote:

I emphasized "might" because I am not quite sure. Like you, I too use lots of macros. Now, I place them at the top. Yes, you can generate an index from them, even make it automatic (special defs?). I find it cumbersome that I can't just include the macros once and have it applied globally.

Special defs? Apologies, I'm new to the docs list. Currently I can just talk all of those [def X [link X /X/]] macros, extract and alphabetize the X's, put them in a section called "index", and I have a kind of glossary/index (glindex?), a list of links to each X's "primary" docs location. But only in html, not in fo-generated pdf. I'm curious as to how you like to generate your indexes.

Another possible behavior would be to get rid of macro scoping at the include level and move them over to the section level as I hinted in my previous email. I'm not yet sure but this seems to be a more practical approach. Either that or we can also have explicit control of macro scopes. I'm leaning towards the former.

Ah, I'd missed that. Personally I think that's the way to go. With unscoped includes and scoped macros, the behaviour is generally more consistent with C++. One could even adopt a convention of .qbk for quickbook files and .qbh for quickbook "headers" of macros. One could concievably even enforce a one-definition rule for macros (though I don't have a good feel for how much trouble that would save people in the long run).

(Oh and BTW, we'll have parametric macros soon so macro names like *something might not work anymore. Again it's a big might. At most, we can allow any character except the parentheses '(', ')', comma ',' and spaces. So the smiley :-) macro in the original QB docs will have to go :-) ).

Awesome. "for" loops, too? (wink)

Anyhow *this *particular *syntax is irrelevant, !anything _would ^work.

-t

Subject: Re: Re: scoped macros From: "troy d. straszheim" <troy@…> Date: Mon, 7 Nov 2005 10:03:31 -0500 Newsgroups: gmane.comp.lib.boost.documentation

On Mon, Nov 07, 2005 at 09:25:52AM +0800, Joel de Guzman wrote:

Oh, BTW, here's the relevant link: ​http://www.xml.com/pub/a/2004/07/14/dbndx.html

Just to flesh out the use-case, I played with this a bit, here's what I came up with... Because of the way links in the index (which point to locations of <indexterm>) and instances of [link T /T/] (pointing to #T) behave differently, it looks like total automation might not be all that straightforward.

The best I've come up with is to create a file "indexterms.dat" containing on each line

<term> <format-char>

e.g.:

sort = back_inserter =

Where generally each line

T ?

in indexterms.dat gets expanded by a script to (indexterms.qbk):

[def *T [link T ?T?]] [def ~T [link T ?T?]<indexterm><primary>T</primary></indexterm>] [def !T <indexterm significance="preferred"><primary>T</primary></indexterm>]

Let all the .qbk files include macros.qbk, which contains the ubiquitous smiley macro and in turn includes this indexterms.qbk. Then at the central point of documentation for T "cpod(T)", you put (longwinded):

#T (drops HTML anchor) [section explanation of T] !T (drops docbook index anchor)

(docs)

[endsect]

and elsewhere, where T is referenced, you use:

*T for a link to #T that does *not* appear in the index, and ~T for a link to !T that also appears in the index.

The good things are:

• the syntax is wicked terse.

• You can sprinkle your docs with links back to the cpod(T) without cluttering the index.

• You (should be able to) get a decent index in printed form with boldface pagenumbers for the pages where !T (significance="preferred") appears.

The ugly bits are:

• You need both *T and ~T, because your html index can quickly get cluttered, since it contains a list of links, the text of which is the titles of the sections that contain the <indexterm> tags. You use ~T only where something useful about ~T is said. If you dropped the requirement to be able to link almost every occurance of T to #T in the html, you could probably get around this, but it's nice. When reading the docs you're almost never more than a click away from cpod(T).

• You can't put #T inside the macro. quickbook would need to delay evaluation (dropping?) of the anchor until after the macros are expanded. e.g. [def !T #T <indexterm significance... (etc) ] doesn't currently work. The #T's appear where the macro is defined, not where it is expanded.

• apache FOP coughs the xml back up with the enlightening error message:

[ERROR] null

and #T and !T don't look like they'd be combinable in one macro anyway, because:

• if T's central point of documentation is typically a [section ...], then putting #T inside the section causes the links to act funny. When you click on the link generated by *T, you get sent to #T, which is just south of the section title. So the title "Documentation for T", which you'd like to see at the top of your page, is "chopped off" (it is just north of the top of the browser page, not visible. Your first impression is that the link was bad.)

• On the other hand, if !T is outside the section definition, the link generated by docbook and placed in the index will take you to the top of the page, not right to the definition, also giving you the impression that the link was bad. Also, the text of the link in the index will be the title of the outer section, not the (desired) innermost one.

Anyhow. Sorry that got a little longwinded.

-t

Subject: Re: Re: scoped macros From: "troy d. straszheim" <troy@…> Date: Sat, 19 Nov 2005 07:53:09 -0500 Newsgroups: gmane.comp.lib.boost.documentation

On Tue, Nov 08, 2005 at 09:45:06AM +0800, Joel de Guzman wrote:

Cool! Very informative. This will guide us through our implementation of QB indexes. Can we peek at some docs where this can be seen in action?

​http://www.resophonic.com/i3book-draft

You can see at the bottom of the first page what the index looks like.

Something came up repeatedly. Since a lot of the content is unix-tutorial, I needed to include a lot of shell-command output, scripts, and so forth, like here:

​http://tinyurl.com/7crvc

"pre" mode isn't ideal: you want to see things wrapped as they look in your xterm, you don't want long urls or compilation commands to run off the right side of the rendered page, and wrapping them yourself is a hassle... Another thing that comes up with [pre ], iirc, is that /unix/path/names/end/up/being/italicized/in/places/ and the neighboring forwardslashes disappear.

and the quickbook itself is easier to read with your shell output is indented like this.

I put together a "vt100" highlighter which wraps at C characters and does no highlighting... (see the wrapping at the tinyurl). The wrapping is never quite perfectly aligned with the right side of the box, but its better than nothing. Can send this on if you want it.

-t

[Daniel James]

There's a lot in this ticket, so I'm not sure what to make of it. But in 1.6 macros and templates are both scoped by file, but can be imported using import, so that should fix the 'scoped macro' part of this ticket.

I'm not sure what to make of the other parts of the ticket. So I'm going to mark this as 'wontfix'. If anything's still desired, probably best to create a new ticket for each feature.