|
This post was updated on Aug 17, 2014; 4:50pm.
Asciidoctor has a [discrete] attribute for section titles that should not be part of the content hierarchy (i.e., it ignores section nesting rules) and should not be included in the TOC (see section 18.6 of the asciidoctor user manual). I'd like to propose a shortcut notation of "#==... "
I was recently experimenting with some source code documentation that was styled in a manpage-like format. The documentation (originally in a customized version of the ROBODoc format) needed to be converted to asciidoc and output as DocBook WebHelp. There was an additional requirement for the sections like SYNOPSIS to not be included in the TOC tree.
At first I thought of using toclevels, but that ended up not being an option given the way the documentation was structured and the fact that DocBook WebHelp builds its own TOC.
I finally ended up offering the option to use block titles (.SYNOPSIS) or labeled lists (*SYNOPSIS* ::), depending on whether they wanted the following paragraph indented or not. However, using section titles would have been nicer since the font style is tied to header tags.
Then I noted the [discrete] attribute and thought it might be wonderful if there was a shortcut notation for specifying discrete titles. For example, it would be nice if using "#== " was possible:
```asciidoc
#== SYNOPSIS
```
The rule would be:
Discrete titles must start with "#==... " in column 0 and are designated by two to six equal signs.
They could also be symmetric
```asciidoc
#==== SYNOPSIS ====#
```
The use of # at the beginning of a line is a comment indicator in many languages and for *nix configuration files, and used for custom styling, which is why I chose it for my discrete shortcut notation proposal (i.e. style this as a section title, but don't use this section title in the TOC). Since using # conflicts with custom styling, custom styled text beginning with "== " could no longer start in column 0.
An alternative would be to place the # inside the equal signs, but IMHO it does not look as nice and is less readable:
```asciidoc
===# SYNOPSIS #===
```
Thoughts?
Thanks,
-Shaun
|