[Nut-upsdev] NUT and AsciiDoc (was: Next AsciiDoc release)

[Arnaud Quette]

Hi Stuart,

sorry for the lag in answering, I know that you're awaiting feedback for the
final release...

2010/10/19 Stuart Rackham

> Hi Arnaud
>
> I successfully compiled all the docs in svn://
> svn.debian.org/nut/branches/AsciiDoc using the current AsciiDoc trunk, and
> yes, the chunked manual only has a single toc. But there was the added
> problem of the article sections not being chunked by default, the
> chunk.section.depth parameter was set to 0 by default (for chapter level
> chunking in books), this has been fixed in the trunk:
>
>
> http://code.google.com/p/asciidoc/source/detail?r=fe13fddfacafe60cc07674aff77a12850dfbde6b
>

excellent, thanks a lot!

The real problem is the inability to specify section level TOCS. Due to some
> myopic thinking on my part, the TOC control is effectively hardwired in
> ./docbook-xsl/common.xsl. I've fixed this so that the TOCs can now be
> controlled via the various DocBook XSL Stylesheets TOC parameters (see
> http://www.sagehill.net/docbookxsl/TOCcontrol.html)
> generate.section.toc.level, toc.section.depth and toc.max.depth:
>
>
> http://code.google.com/p/asciidoc/source/detail?r=a40a136d131225d042536c781082181f06024c33
>
> I can now generate a TOC in each section of the user-manual by setting the
> generate.section.toc.level to 1 e.g.
>
> a2x -v --attribute icons --attribute localdate=`TZ=UTC date +%Y-%m-%d`
> --attribute localtime=`TZ=UTC date +%H:%M:%S` --attribute iconsdir=./icons
> --attribute=badges --attribute=external_title -a toc -a numbered
> --destination-dir=. --format=chunked --xsltproc-opts "--stringparam
> generate.section.toc.level 1" user-manual.txt
>
> Use the toc.section.depth to increase the depth e.g.
>
> a2x -v --attribute icons --attribute localdate=`TZ=UTC date +%Y-%m-%d`
> --attribute localtime=`TZ=UTC date +%H:%M:%S` --attribute iconsdir=./icons
> --attribute=badges --attribute=external_title -a toc -a numbered
> --destination-dir=. --format=chunked --xsltproc-opts "--stringparam
> generate.section.toc.level 1 --stringparam toc.section.depth 3"
> user-manual.txt
>
> I also tried generating the user-manual using the 'book' doctype, this
> picked up an (unrelated) problem -- I got the following error:
>
> a2x: finding resources in:
> /home/srackham/tmp/AsciiDoc/docs/user-manual.chunked/ch03.html
> Traceback (most recent call last):
>  File "/home/srackham/bin/a2x", line 814, in <module>
>    a2x.execute()
>  File "/home/srackham/bin/a2x", line 343, in execute
>    self.__getattribute__('to_'+self.format)()
>  File "/home/srackham/bin/a2x", line 625, in to_chunked
>    self.copy_resources(html_files, src_dir, dst_dir)
>  File "/home/srackham/bin/a2x", line 509, in copy_resources
>    lambda attrs: attrs.get('type') == 'text/css')
>  File "/home/srackham/bin/a2x", line 240, in find_resources
>    parser.feed(open(f).read())
>  File "/usr/lib/python2.6/HTMLParser.py", line 108, in feed
>    self.goahead(0)
>  File "/usr/lib/python2.6/HTMLParser.py", line 148, in goahead
>    k = self.parse_starttag(i)
>  File "/usr/lib/python2.6/HTMLParser.py", line 249, in parse_starttag
>    attrvalue = self.unescape(attrvalue)
>  File "/usr/lib/python2.6/HTMLParser.py", line 387, in unescape
>    return re.sub(r"&(#?[xX]?(?:[0-9a-fA-F]+|\w{1,8}));", replaceEntities,
> s)
>  File "/usr/lib/python2.6/re.py", line 151, in sub
>    return _compile(pattern, 0).sub(repl, string, count)
> UnicodeDecodeError: 'ascii' codec can't decode byte 0xc2 in position 6:
> ordinal not in range(128)
>
> This error is due to a limitation in the Python HTMLParser module, see:
> http://bugs.python.org/issue3932
>
> I resolved it by assuming UTF-8 input (this assumption is not always going
> be correct but it will be correct more often that not doing anything and
> assuming an ascii encoding:
>
> http://code.google.com/p/asciidoc/source/detail?r=c9656a70e1303022b041646ef99bef205e6e7f9e
>
> So, to to get section level TOCs you need to run from the trunk and pass
> TOC XSL Stylesheets parameters to a2x using the --xsltproc-opts option.
>
> Could you please test and report back.
>

AFAICT, everything is working as expected ^_^
thanks again for your action on the NUT specific issues, and more generally
for this "holy grail" you brought us!

I'll now get back on the final NUT completion. Once done and available on
www.networkupstools.org (it's currently only on new.n.o), I'll ping you back
for a reference in the "Documents written using AsciiDoc" section.

cheers,
Arnaud
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.alioth.debian.org/pipermail/nut-upsdev/attachments/20101022/d913af18/attachment.htm>