[TYPO3-doc] View manual(s!).html of TER extensions fast!

[Martin Bless]

See here what you can get at the moment:
http://preview.docs.typo3.org/typo3/extensions/


I'm working on a build chain that:

- fetches the TER extensionlist extensions.xml.gz
- (w)gets the new manual.sxw from TER
- parses these OpenOffice documents to ReST
- creates a single HTML file from ReST

If you are an extension author and your manual doesn't show up:
Continue reading. Maybe you can provide a "better" or newer manual.sxw
with your next upload. Type in the URL, that is, go manually to:
http://preview.docs.typo3.org/typo3/extensions/EXTKEY/
to see what might be going wrong. All extensions from TER should have
their folder.


What you may want to know and where you can help
================================================

I have turned the table rendering in this build chain ON again as
provides much better readability - which is the main purpose here.

(1)

I'm wgetting the manuals simply by guessing and trying this URL
scheme:
http://typo3.org/extension-manuals/EXTKEY/VERSION/sxw/?no_cache=1

Q: If you are a TYPO3 insider and know better: let me know.

If this wget doesn't succeed that's reason number one for not getting
an output.


(2)

Afterwards the manual is converted by OpenOffice from manual.sxw to
manual.html This (very?) often fails because OpenOffice complains
about the file being corrupted. My local LibreOffice give the same
note but is willing to repair the file - which succeeded in some
examples I tried. 

Q: If you know something about this "manual.sxw is corrupted" issue or
OpenOffice commandline switches that help to overcome this
automatically: Please let me know.

If the conversion to HTML doesn't succeed that's reason number two for
not getting an output.


(3)

It looks like that once we have the HTML output from OpenOffice the
steps up to parsing into ReST markup always succeeds. Cool!


(4)

Finally the ReST file should be rendered to HTML again creating
'index.html'. This currently probably very often fails for simple
reasons. Unfortunately many manuals have a 
"-----
For integrators, ...
"
in the meta data. This isn't legal ReST syntax!


(5) Index file at typo3/extensions/:

This index file shows links to those extensions for which we have
rendering. http://preview.docs.typo3.org/typo3/extensions/

In fact there may be many more as the link always point to the latest
version WITH a successful rendering. But you may always wander around
the directory structure as directory listing is ON:

For example:
http://preview.docs.typo3.org/typo3/extensions/a21glossary/


But not all may be "good":

This is what you get when wget couldn't fetch a manual:
http://preview.docs.typo3.org/typo3/extensions/a21glossary/0.3.0/


This is a "good" one:
http://preview.docs.typo3.org/typo3/extensions/a21glossary/0.9.4/


This is a "bad" one where OpenOffice can't read the manual and
complains about a corrupted one:
http://preview.docs.typo3.org/typo3/extensions/aahbook_plus/0.0.3/sxw2html-conversion-error.txt


This is a "bad" one where the ReST to HTML conversion fails:
http://preview.docs.typo3.org/typo3/extensions/aux_newsmailer_split_cat/1.0.5/
(Oops, I just notice, that the warnings.log is empty which it
shouldn't be).

Good:
http://preview.docs.typo3.org/typo3/extensions/aux_newsmailer_split_cat/2.1.0/


Once it works it isn't very costly in terms of server load.

It's all very fresh and new but I wanted to let you know. OTH it's
useful already I would say.

If you have ideas to make the world a better place: Let us know!

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de