João Abecasis wrote:
I've already run into a number of situations where I'd like to have
some missing functionality. Here are a few items:
- Chapters, _a_la_ LaTeX
- Subsections, _a_la_ LaTeX
I'm not sure what you're after, I'm not all that familiar with LaTeX.
FWIW, you can nest [sections] in QuickBook.
That might be good enough for what I need at the moment. In LaTeX
one can attach ordering indicators (numbers, for example) to sections.
The type of indicator depends on the style chosen. For example, a
research paper is typically structured like this:
\section{Overview}
Some text...
\subsection{First Subject Area}
More text...
\subsection{Second Subject Area}
Still more text...
and with, say, an IEEE style, it ends up looking like this:
1. Overview
Some text...
1.1 First Subject Area
More text...
1.2 Second Subject Area
Still more text...
One can do \subsubsection, \paragraph, etc. to refine this even more.
This may be overkill for the goals of Quickbook. Mostly I'd just
like the ability to organize information without resorting to faking
it with different header styles. It sounds like the ability to
nest sections is just what I need.
- A way to specify HTML page breaks (i.e. put everything after this on
a new page). These may or may not specify page breaks for other
outputs. Perhaps multiple break types would be useful.
There are no explicit page breaks in QuickBook. I think you can get
something similar with sections. This is more the domain of DocBook, I'm
not sure what are (y)our options here.
I think you're right about sections and that's one of the reasons
I was asking about subsections and chapters. How does the break
algorithm work in the presence of nested sections. Basically, I
want to avoid creating mega web pages that present too much information
at one time.
- Footnote/bibliography/reference support (can fake it, but it's
awkward)
Eric added footnotes some time ago:
[footnote footnote_text]
Cool!
- A way to reference code snippits directly from source files. This
seems complicated but would be really useful to keep
documentation/code examples up-to-date with actual implmentations.
Perhaps some special marker comment in the code could be referenced
to import into a .qbk. Kind of like a literate programming system
but without the awful code mangling it implies. I've read about
systems like this called "Elucidative Programming:"
http://www.cs.auc.dk/~odin/thesis/
I haven't looked at the link for now, but something along those lines
was discussed some time ago, but there is no implementation as of yet...
Part of the idea was to add scripting support and to allow for the
manipulation of code snippets inside QuickBook as well as to extract
them from separate source files.
This would be super-cool. Already I inserted a code snippet from my
project and it changed within five minutes. :)
Another feature I neglected to mention:
- Ability to mark some documentation as "hidden" or "internal."
Basically, this would allow a single specification to generate
documentation for, say, internal use and also generate a
smaller document with less detail intended for wider distribution.
This would be particularly useful for my current project.
Thanks for your great work!
-Dave
-------------------------------------------------------
This SF.Net email is sponsored by xPML, a groundbreaking scripting language
that extends applications into web and mobile media. Attend the live webcast
and join the prime developer group breaking into this new coding territory!
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=110944&bid=241720&dat=121642
_______________________________________________
Boost-docs mailing list
[email protected]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
