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

[Thomas Berezansky]

Or we can just define leveloffset like some of the other doc files  
already do for including things, giving us standalone-capable files  
that also stack nicely on each other.

Most useful when doing actual include:: stuff, but applies even when not.

http://www.methods.co.nz/asciidoc/userguide.html#X90

Thomas Berezansky
Merrimack Valley Library Consortium


Quoting Bill Erickson <erickson at esilibrary.com>:

>
> Speaking of release notes, I remembered something I wanted to bring  
> up back when cutting beta1.
>
> When we create asciidoc files to add to docs/RELEASE_NOTES_NEXT/,  
> our instinct is to create a standalone file that asciidoc can parse.  
>  That usually means starting a document with a "===" header and  
> working down from there.  The problem with this approach is that  
> stitching the files together into a single set of release notes  
> requires manual intervention to repair the heading levels.  If we  
> assume the standard structure for RELEASE_NOTES_X_Y.txt will take  
> this form:
>
> Release notes
> =============
> :toc:
> :numbered:
>
> Upgrade notes
> -------------
>
> <stuff>
>
> Coming Soon.
>
> New features
> ------------
>
> Feature Group
> ~~~~~~~~~~~~~
>
>
>
> ... 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?
>
> -b
>
> --
> Bill Erickson
> | Senior Software Developer
> | phone: 877-OPEN-ILS (673-6457)
> | email: erickson at esilibrary.com
> | web: http://esilibrary.com
> | Equinox Software, Inc. / Your Library's Guide to Open Source
>