[Nut-upsdev] svn commit r1997 - in branches/AsciiDoc: . docs docs/man docs/website

[Arnaud Quette]

2009/9/21 Arnaud Quette <aquette.dev at gmail.com>

>
>
> 2009/9/21 Charles Lepple <clepple at gmail.com>
>
>>
>> On Sep 21, 2009, at 7:28 AM, Charles Lepple wrote:
>>
>>  On Sep 21, 2009, at 5:52 AM, Arnaud Quette wrote:
>>>
>>>  Subject: svn commit r1997 - in branches/AsciiDoc: . docs docs/man
>>>> docs/website
>>>> Author: aquette
>>>> Date: Mon Sep 21 09:51:09 2009
>>>> New Revision: 1997
>>>>
>>>> Log:
>>>> switch INSTALL to AsciiDoc, and name it as the "Quick Start
>>>> Instructions".
>>>> Also includes various minor updates to the User Manual and Packager
>>>> Guide.
>>>>
>>>
>>> Arnaud,
>>>
>>> not sure why Buildbot did not send out an email regarding this, but the
>>> AsciiDoc build failed for this revision:
>>>
>>> /usr/local/bin/asciidoc --unsafe --backend=xhtml11 \
>>>                --attribute icons \
>>>                --attribute localdate=`TZ=UTC date +%Y-%m-%d` \
>>>                --attribute localtime=`TZ=UTC date +%H:%M:%S` \
>>>                --attribute iconsdir=./icons \
>>>                --attribute=badges \
>>>                -a toc -a numbered -o user-manual.html user-manual.txt
>>> ERROR: cables.txt: line 2: only book doctypes can contain level 0
>>> sections
>>> make[1]: *** [user-manual.html] Error 1
>>>
>>>
>>
> yup, sorry. I missed to fix that before commiting...
>
>
>>  Looking a little closer, it seems that we have two conflicting goals
>> here:
>>
>>  * having standalone web pages with automatic titles ("level 0 sections")
>>  * being able to include the same page in a larger document
>>
>> Maybe there is a way to set the page title attribute if it has not already
>> been set by an including document?
>>
>> Unfortunately, this loses some of the simplicity of AsciiDoc.
>>
>
> I'm looking at that currently, but this was the main reason for not
> including a level 0 title in docs like features, cables (included both the
> website and the doc, itself pointed as a whole in the website).
>
> ATM, the lightest solution I have is to conditionaly declare the level 0
> title in the doc if we don't have a "website" attribute. otherwise (ie we're
> included in the doc), the title is declared in the includer.
>
> I'm also redefining the levels in user manual with:
> :titles.underlines: "__","==","--","~~","^^"
>
> The other way is to not define a level 0 title, and force "doctitle=name"
> in the Makefile.
>
> I'll finish the test approach #1 to see if it fits all cases...


I forgot to add that this is not the best for plain text readibility, ie the
title of the file changes from:
Features
========

to

ifdef::website[]
Features
========
endif::website[]

but we can still generate plain text, along with the html. And this should
remove (ie interpret) the macros...

cheers,
Arnaud
-- 
Linux / Unix Expert R&D - Eaton - http://www.eaton.com/mgeops
Network UPS Tools (NUT) Project Leader - http://www.networkupstools.org/
Debian Developer - http://www.debian.org
Free Software Developer - http://arnaud.quette.free.fr/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.alioth.debian.org/pipermail/nut-upsdev/attachments/20090921/d33d9a7f/attachment.htm>