[Boost-bugs] [Boost C++ Libraries] #1189: Scoped Macros

Subject: [Boost-bugs] [Boost C++ Libraries] #1189: Scoped Macros
From: Boost C++ Libraries (noreply_at_[hidden])
Date: 2007-08-20 07:28:06

#1189: Scoped Macros
------------------------------+---------------------------------------------
 Reporter:  djowel            |       Owner:  djowel   
     Type:  Feature Requests  |      Status:  new      
Milestone:  To Be Determined  |   Component:  quickbook
  Version:  Boost 1.34.1      |    Severity:  Problem  
 Keywords:                    |  
------------------------------+---------------------------------------------
 This may be relevant to the current plan to scope macros and templates.
 Excerpt follows:
 --------------------------------------------------------------------------

 Subject:
 scoped macros
 From:
 "troy d. straszheim" <troy_at_[hidden]>
 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_at_[hidden]>
 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_at_[hidden]>
 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_at_[hidden]>
 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

-- 
Ticket URL: <http://svn.boost.org/trac/boost/ticket/1189>
Boost C++ Libraries <http://www.boost.org/>
Boost provides free peer-reviewed portable C++ source libraries.