The problem with book - like formats (like PDF and epub) is the
necessity to lay out the document in a page like fashion. So
you get page 1, page 2, page 3 etc... up to page n. The wiki
is a different beast as it's a collection of html pages linked together
by means of an index. There is no first page, third page, last page
etc....
epub is essentially nothing but a bunch of html files + an index. It
is a bit like chm. Producing a chm should be much like
producing a epub. With the difference that epub requires you
to give a list of all the pages in the document.
On the upside epub accepts html pages so no translation is needed.
And an epub can be read on a mobile device.
On the downside epub does not come with a search facility like
chm does (referring to the index tab of the chm browser). It largely
depends upon the mobile device used whether there is a proper
index or not. When I use the chm manual I almost always use
the index tab to look up a word.
PDF is a completely different kind of thing. Again you need to sequence
the pages. But the concept of a page is different. A page has a fixed
length depending on the format used (usually either A4 or US Letter).
To convert a html page to a pdf page might require breaking up
the html file into several pieces. There are few free libraries that can lay
out pdf in such a way that this breaking of pages is done correctly
(hyphenation is an issue as well: line breaking should be done correctly).
A PDF has a similar index to epub and lacks the search facility of the
compiled html browser (as does epub). It's that search faciilty that's
key to the ease of using the chm manual.
When I have a proper sequencing of the pages (cannot be done
automagically) creating a pdf version of the manual becomes somewhat easier.
Html tags translate directly to calls to routines in pdflib and
pdflib can do the hyphenation and splitting of the pages as well.
It will no doubt lead to pages with lots of whitespace on them.
The main reason I want to create an epub version of the manual is threefold.
First of all I am seeing other projects releasing manuals in epub/pdf format.
A prime example of this is python. Python come with a manual in pdf, html, epub and
compiled html format (python uses sphinx for creation of the manual.
Sphinx uses latex for creation of the pdf file).
Secondly I have my doubt about the future of compiled html. It is somewhat of a deprecated
format. If a format comes along with equally good searching facilities (the index tab of the chm
browser is, at least on windows, unchallenged) then the days of compiled html are numbered
(the next epub standard could just provide such a facilitiy).
Thirdly the companies behind the epub format are looking to expand the epub standard.
It's clear they want to replace the pdf format with epub. Even Adobe is a member of the idpf
http://idpf.org/ (Adobe has released a pdf reader). The next pdf version would have been an
xml based format but Adobe has never released that next version and instead seems to have
opted to support the epub standard. epub seems to be THE format for electronic books.
The thinking here is that because epub will replace both pdf and chm future releases
of freebasic might need to come with only one manual: an epub one.
As the online wiki is already in html format it makes sense to use those pages to create an epub.
@TJF
I have seen your devhelp effort. devhelp seems to have the same indexing facility as the
chm browser. The only problem with devhelp is that I have not found a windows binary for it yet.
Creating binaries for a gtk+ related project like devhelp tends to be hard (it has a webkit
dependency which will make compilation that much harder) which might make devhelp a one -
platform solution. Given a devhelp binary I can see myself using a manual in devhelp format
instead of one in compiled html format. But you'd have to deliver either the devhelp binary or
a link to such a binary with the manual (otherwise you run the risk of win32 users having
to search for a devhelp binary themselves).
I thought about decompiling the chm file and using those html files as starting point for
the creation of an epub file. But those html files differ from the ones that are created by the
wakka parser (the php program that turns .wakka files into .html pages).
I am hoping to release an epub version of the manual soon (end of this week or end of next
week). A pdf version would be nice to have and it all depends upon the ease of use of
libpdf and coming up with a proper translation of html tags/the cascading style sheet
that comes with the online wiki. For the creation of the epub I can simply reuse the
online wiki pages (copy most of the content/change wiki pages a tiny bit).
More work is needed for the creation of a pdf version of the manual (the wiki pages need
to be parsed much more precise in order to generate appropriate calls to pdflib functions).