[OPEN-ILS-DEV] Formatting for RELEASE_NOTES_NEXT/*

[Dan Scott]

On Fri, Aug 24, 2012 at 11:02:29AM -0400, Bill Erickson wrote:
> 
> Speaking of release notes, I remembered something I wanted to bring up back when cutting beta1.

<snip>
 
> ... then the files in docs/RELEASE_NOTES_NEXT/ should look like this:
> 
> 
> Feature Name
> ^^^^^^^^^^^^
> 
> We built this city on rock and roll
> 
> Feature Sub-Heading
> +++++++++++++++++++
> 
> * Marconi plays the mamba
> * listen to the radio
> 
> 
> In other words, start each file in docs/RELEASE_NOTES_NEXT/ at the "^^^" heading level.
> 
> Asciidoc will warn when compiling such a file:
> 
> WARNING: foo.txt: line 2: section title out of sequence: expected level 1, got level 3)
> 
> but it will still compile, so you are able to verify the syntax.
> 
> Sound sane?

Sane, but completely unnecessary.

Asciidoc lets you offset the levels of included files, idea being that
you might want to recombine individual topics at different levels in
different publications. So what I've been doing in the DIG docs when I
add a topic is add a normal top-level Asciidoc file, then offset it when
I include it.

Commit 1b0ec3546c727 is a pretty good example of that. I created a file
called "opac/search_form.html" with a structure like:

"""
Adding an Evergreen search form to a web page
=============================================

To enable users to quickly search your Evergreen catalog, you can add a
simple search form to any HTML page. The following code demonstrates
how to create a quick search box suitable for the header of your web
site:

.Sample search form
[source,html]
"""

and then included it into the root.txt file as follows:

"""
// Push titles down one level.
:leveloffset: 1

include::opac/search_form.txt[]

// Return to normal title levels.
:leveloffset: 0
"""

You can include as many files as you like within a given offset section,
so we would only need to put one pair of offset directives in the
release notes container file, and just include the entries there.

I've been meaning to bring this up at DIG to hopefully standardize on
this approach, as it would make generating standalone HTML files to link
from the staff client help a lot more straightforward, and would also
simplify the creation of subsets of the documentation for tutorials,
etc.