On 8/5/07, David Chisnall <[EMAIL PROTECTED]> wrote: > On 6 Aug 2007, at 00:09, Yen-Ju Chen wrote: > > > I was thinking that we put both API document for frameworks > > and user manual for applications at the same directory structure. > > So user manual for StepChat will be under > > Etoile/Services/User/Jabber and API document for TRXML > > will be under Etoile/Services/User/Jabber/TRXML. > > While API documentation is automatically generated, > > use manual are writtein by hand, which is not that easy to do > > with rsync and sftp, especially for collaboration as source code. > > User documentation is likely to include at least one step for > automatically generating cross-references. As long as it puts the > built version in a specific location a publish-docs: rule in the > makefile could easily push them off to the server. For a detailed > user manual, you are likely to want to use something like LaTeX and > use pdflatex or tex4ht to produce PDF and HTML output, so you'd keep > the documentation source (the .tex files) in subversion, and push the > HTML online periodically.
I was hoping that if the directory structures of user documentation is fixed, we don't need to automatically generate user documentation for cross-reference. The plain HTML will do for user manual. I personally dislike most of the authoring tools, such as docbook or LaTex. It just adds another layer of troubles. I don't have enough experience here. But people (includeing me) are more likely to write documentation when there is less overhead. Yen-Ju > > David > > _______________________________________________ > Etoile-discuss mailing list > [email protected] > https://mail.gna.org/listinfo/etoile-discuss > _______________________________________________ Etoile-discuss mailing list [email protected] https://mail.gna.org/listinfo/etoile-discuss
