[Scummvm-devel] Documentation

James 'Ender' Brown ender at scummvm.org
Sat Dec 22 02:07:02 CET 2007


I'm probably partly to blame with originally pushing for a wiki'fication
of the manual, as writing in DocBook or LaTeX is daunting to some
people... and even people with SVN write access were on occasion
updating the generated alternate formats instead of the source file.

On the other hand, it is fairly simple to export the current manual in
the Wiki as a variety of HTML formats (multi-page, single-page). These
can in turn be processed to fairly nice PDF using a variety of means,
although there has been some argument in the past about optimization
(personally, KDEs Print to PDF using KHTML to render and GS to generate
PDFs always seems to come out nicely for me).

HTML is easy enough to render in plain text, PDF, eCHM, and of course
multi-page and single-page HTML.

The next step would actually be to use some kind of pseudo-template
language if we _really_ wanted to produce multiple documents from the
same source - eg, a cutdown README and a full-blown Manual. But how much
material is really shared verbatim?

The three options I see, with regard to Wiki documentation (one of the
advantages of DocBook is several methods to do this already) are to
either:
  * Seperate documents, manually synced
  * Sections copied verbatim could be included via Wiki Templates from a
shared subpage/namespace
  * We could use custom (very basic) markers in the source and parse
during HTML export - eg, '
  <!--BLOCK="mass_add", HIDDEN="compatibility", DISPLAY="manual,
readme"-->
  <!-- END BLOCK -->

My questions are:
  * What formats do we ultimately need to export in? Text, html, eCHM
and PDF should cover everything imho. One can even use existing HTML
features such as ALT tags for replacement in text-only documents
  * Are there really many occasions we would need to reuse text verbatim
between the full manual and a lesser README? (IMHO, with a proper manual
the README should just point people there - instead of trying to act as
a stand-alone 'Quick start' guide)

This is my $2.20 :)

 - Ender


On Thu, 2007-12-20 at 20:44 +0000, Henry Bush wrote:
> OK, I've been thinking about this on my walk home.
> 
> Why did the manual get moved (or copied) to the wiki in the first
> place? I suspect (though I wasn't involved in discussion, correct me
> if I'm wrong) in order to try and promote it, and to get more people
> contributing.
> 
> The only benefit to having the manual on the wiki that I can see is
> that it's easier to edit, and that doesn't seem to have made any
> difference to the number of people contributing. On the other hand,
> the benefits of a docbook (or similar) manual are huge: easy
> conversion to almost any format (including multi-page html), easy
> creation of multiple documents for different purposes (e.g. different
> readme for different ports, etc), and I'm sure there are others.
> 
> I don't want to come across dictatorial (especially where I have
> absolutely no place to be), but what do people think about the
> proposal of scrapping the wiki manual and switching back to docbook?
> 
> There may be a little content overlap with the wiki, but with suitable
> links, both wiki->manual and manual->wiki, I think we can minimize it.
> 
> Thoughts?
> 
> 
> Henry
> 
> -------------------------------------------------------------------------
> This SF.net email is sponsored by: Microsoft
> Defy all challenges. Microsoft(R) Visual Studio 2005.
> http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
> _______________________________________________
> Scummvm-devel mailing list
> Scummvm-devel at lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/scummvm-devel
> 





More information about the Scummvm-devel mailing list