On Mon, 2009-05-25 at 12:52 +0200, [email protected] wrote: > Hi, > > As an acting maemo doc manager (and when I now had time to read also this > mailing list) I added my comments to this thread. > > Let me start by saying that you had very good points below Murray!! > > Date: Mon, 25 May 2009 10:11:47 +0200 > From: Murray Cumming <[email protected]> > Subject: Re: The role of the docmaster > To: List for community development <[email protected]> > Message-ID: <1243239107.10207.7.ca...@murrayc-desktop> > Content-Type: text/plain > > On Tue, 2009-05-19 at 14:56 +0200, Murray Cumming wrote: > > At the risk of "me too"ing, I've been loosely involved in various random > > parts of the Maemo documentation, and I've been a (often dissatisfied) > > reader of the rest. The problems are totally fixable. These would be my > > priorities: > > > > My priorities have been following (since about year and half ago e.g. since > Chinook). > > 1. Cleanup existing Chinook documentation for Diablo > - end result for that was Diablo Reference Manual and example apps in Garge > http://maemo.org/maemo_release_documentation/maemo4.1.x/
This is a combination of all the existing documentation, right, as one big PDF? Or does this contain information or modifications that are not in the regular API reference. For instance, http://maemo.org/api_refs/5.0/beta/hildon/index.html By the way, though I understand that big printable PDFs are useful and important for certain customers, it really shouldn't be your priority. The most important stuff is what google can find and what people can paste as URLs when discussing the APIs. > https://garage.maemo.org/svn/maemoexamples/tags/maemo_4.1/ > - base reference manual to the example applications so that all example code > used in manual is testable > > 2. Rise Diablo release documentatin about to the same level as Chinook/Diablo > training material was > - e.g. Diablo Reference Manual (release documentation) was based mostly to > the training material > - existing separate Chinook how-tos were (somewhat) unified and added to the > Reference Manual > > 3. Create documentation infrastructure that can handle very big documents and > is independent from format that is used to publish documents > - Diablo Reference Manual and Training Material is now in Latex format and > Latex can handle very big documents > - From latex we are able to generate all needed release formats e.g. for > Frementle we are able to release same docs wit high quality as PDF docs, HTML > docs and MediaWiki docs. > - next output format will be Eclipse xhtml The developers who are able to help you are used to editing DocBook XML, gtk-doc and doxygen. The tools they use (library.gnome.org, DevHelp) use these formats. DocBook (and DocBook processors) has no particular problem with large files. DocBook is very standard and popular and can output to these formats with fop (or one of the even-better proprietary processors). Well it probably does not generate Mediawiki markup, because why on earth would you want to generate content for a wiki. Generated content should not be edited in the generated form. I can probably help you to do what you need with DocBook. And I sincerely hope that you are not thinking of forcing the gtk-doc and doxygen content into latex. > 4. Allow maemo community to contribute maemo docs in future and still release > official reviewed versions > - plan is that we release prereleases from maemo documentation together > with SDK prereleases in maemo.org wiki so that maemo community can contribute > - plan is that official (final releases) for docs are releases as HTML docs > in Midgard (snapshots for final releases) > - plan (in future when we have latex -> xhtml conversion done) is that > official (final releases) for docs are releases as Eclipse XHTML to gether > with Eclipse Integration [snip] Sorry, but this is all so terribly wrong. I can only suggest that you read my email again. The main problem is that the content is currently not good enough. This awful system is stopping us from identifying problems and fixing them. -- [email protected] www.murrayc.com www.openismus.com _______________________________________________ maemo-community mailing list [email protected] https://lists.maemo.org/mailman/listinfo/maemo-community
