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

[Mike Rylander]

On Fri, Aug 24, 2012 at 11:14 AM, Dan Scott <dan at coffeecode.net> wrote:
> 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.

That works fine when you intend to keep the included files around and
separate, but I thought that the intention with the release notes as
to have one file that absorbs all the smaller ones.  No?  If I
misunderstand, or if I don't but keeping the individual files around
is better and obvious to all but me, then, well, never mind.

-- 
Mike Rylander
 | Director of Research and Development
 | Equinox Software, Inc. / Your Library's Guide to Open Source
 | phone:  1-877-OPEN-ILS (673-6457)
 | email:  miker at esilibrary.com
 | web:  http://www.esilibrary.com