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

[Bill Erickson]

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