troy d. straszheim wrote:
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...
Most welcome!
I was about to post something about macro scopes.
The current scoping behavior came after a brief chat
between me and Eric while he was writing the include
facility. I realize now that it *might* not be the best
behavior.
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.
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.
Let me know your thoughts.
(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 :-) ).
Regards,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net
-------------------------------------------------------
SF.Net email is sponsored by:
Tame your development challenges with Apache's Geronimo App Server. Download
it for free - -and be entered to win a 42" plasma tv or your very own
Sony(tm)PSP. Click here to play: http://sourceforge.net/geronimo.php
_______________________________________________
Boost-docs mailing list
[email protected]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
