John Maddock wrote:
But then, this gets me thinking, why don't h1 through h6
automatically translate to the-current-section-level plus 1-to-6?
Then the new [h Heading] would be a shorthand for [h1 Heading]. Is
there a reason why one would ever want to hardcode hN in the docs?
Good idea! Make it relative, instead of absolute. I have one reason
against it however: backward compatibility. I do have some docs with
hard coded hNs. Those were the ones that were quick-ported from the
good old days of QuickDoc. Well, we have version checking anyway,
so we can apply it only to 1.3 and above. And it's always easy to
grep those hNs.
There's another (minor) reason against it: syntax. The original
syntax was taken from HTML, which behavior is absolute; not
relative. Might there be some confusion? No?
I have lots of hard coded header levels as well: which I use when I
don't want to start a new section.
Same here. In my case, however, headings in a particular section
is just flat. Example:
[section A]
[hN X]
[hN Y]
[hN z]
[endsect]
Where N is the section level plus one. So, I find it tedious to
scan the section level everytime. Hence, my need for generic
headings, so I can just rewrite all [hN Heading] as [h Heading]:
[section A]
[h X]
[h Y]
[h z]
[endsect]
They work well regardless where you place them. You can rearrange
sections at will without any extra work to ensure correct heading
levels.
How about [h+2 ...] fairly obvious then that it's relative, and it's
backwards compatible too?
Yes, that would work. The question is: are they really needed?
As for me, I don't need them. IMO, if you want different
heading levels, it's better to use nested sections instead.
Even absolute headings seem redundant to me now, yet, I'm all
for backward compatibility, so IMO it should stay.
Regards,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net
-------------------------------------------------------
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
