ipernity API development / Discussions

Great idea! :-)

I won’t use it, but if there were one, this would be an improvement for some users :)

I don’t know, what system is used at ipernity for displaying the API help, but it should be extended for automated PDF generation. If it will be done anually each time, the API gets extended or changed, this will be a lot of work (or the two documentations are in different states, if the PDF version will not be updated regulary).

--
Coming from a group home page (?)

The API doc in a set of XML files. We will propose soon an API method to download the method XML description files.
So I guess those files could be exported in any formats.

You could write it in a format that's convertible to various other formats.
For example sphinx for Python documentation,
it can output HTML and LaTeX (=>PDF).
And reStructuredText is so much easier to write than HTML...

Like XML, that can be processed by all programming languages i know? ;)

You just need an XML parser that outputs the formatted API documentation contents as PostScript and then convert it to PDF. I guess, it’s not THAT hard, if the XML files for the API documentation are created in a “clean” way without missusing tags.

Maybe there is a possibility to directly convert the output, but it doesn’t matter, because it’s just one line for converting the PostScript document:

convert api.ps api.pdf

(yes, you’re right: ImageMagick is able to process PostScript files *g*)

--
Coming from a group home page (?)

The API HTML documentation pages are generated from XML files. So I guess it will be easy to convert them in PS or PDF. Do you know how to create PS ? or PDF ? This will save me some time searching how. Thanks!

There is a lot of conversion tools for XML to TeX (and then to PDF/PS). You might want to look at XMLTeX, it looks promising. (Note: I have never tried this...)

There is a DANTE Talk in german: www.dante.de/dante/events/mv27/handouts/partosch-xml/S-05 (DANTE is the german TeX Users Group). On this page there's allso some awk tricks to convert from XML to TeX.

See above, XSLT is the right way. I can help you if you like.

"you just need" - that's how all evil starts.
reStructuredText was made to write text documents, XML not.
Yes, I am aware that I could also write a parser for SuperBizzaro documents
and convert it to any other possible format.

Hint: Write a XSL Stylesheet and use XSL Formatting Objects to create PDF files.

Well, i tested it. If you have a PostScript file, you really just need convert to get an PDF file ;)

--
Seen in a group discussion (?)

I suggest Docbook instead of horrible standards like XML and XSL. These are nice to process data, but not for writing documentation. Docbook is more human readable and you are able to convert in any format you like (ascii, latex, pdf, postscript).

I never understood how people could chasten themself by writing configuration files (like e. g. the Jabberd config) or documentation in XML or XML-like languages

How complicate is it to generate a Docbook XML ?

Docbook is XML ;)

<?xml version="1.0" encoding="UTF-8"?>
<book xml:id="simple_book" xmlns="docbook.org/ns/docbook" version="5.0">
<title>Very simple book</title>
<chapter xml:id="chapter_1">
<title>Chapter 1</title>
<para>Hello world!</para>
<para>I hope that your day is proceeding <emphasis>splendidly</emphasis>!</para>
</chapter>
<chapter xml:id="chapter_2">
<title>Chapter 2</title>
<para>Hello again, world!</para>
</chapter>
</book>


--
Coming from a group home page (?)

My bad- i actually meant "Asciidoc" and not "Docbook" => www.methods.co.nz/asciidoc