id summary reporter owner description type status milestone component version severity resolution keywords cc 1189 Scoped Macros Joel de Guzman 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"" 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"" 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"" 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 ) 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 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?]'''T'''] [def !T '''T'''] 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 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] ''' 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 " Feature Requests closed To Be Determined quickbook Boost 1.34.1 Problem wontfix