[RFC] Documentation of videolan

[Sigmund Augdal]

I think that using Doxygen for API documentation is deffinitly 
worthwhile. I think that, with a litle bit of bashing, doxygen can
be used to generate libvlc documentation (for people wanting to use 
libvlc in other apps), documentation for module developers (who don't 
want to touch vlc core) and core developers (that need to find out what 
that strange function is supposed to do).

have a look at http://s133b.studby.ntnu.no/vlc/html/ (not available at 
night) to see what doxygen can do woth the current vlc tree.

Sigmund
Den 2002.09.13 14:12 skrev Alexis de Lattre:
> 
> These are my ideas on how the documentation of videolan should evolve
> in
> the coming months. I would like to have your comments on my ideas.
> 
> First, the problems with the actual documentation :
> 
> - we only build it in HTML,
> 
> - there are redundancies between the 4 user documentations
> (Introduction, explaination on how to install the softs and a
> satellite
> card for example...)
> 
> - some documentations are out of date...
> 
> 
> My idea is to transform all the documentations in DocBook format and
> segment the sections in separate files so that we can include the
> files
> in more that one documentation.
> 
> 
> For example, the description of the installation of vlc could be in
> one
> Docbook file and included in :
> 
> - VideoLAN Quickstart
> 
> - VideoLAN HOWTO
> 
> and used to generate :
> 
> - the text file "INSTALL" in the CVS and tarballs
> 
> 
> Another example is the FAQ for vlc (same for vls) which could in
> included in :
> 
> - VLC HOWTO
> 
> - the text file "FAQ" in the CVS and tarballs
> 
> - a separate HTML page on the Web site.
> 
> 
> My other idea is for the options of the command line of vlc and their
> description. It could be in Docbook format and then transformed in
> other
> formats so that it could be included in :
> 
> - vlc --help (I don't have a precise idea on how to to that)
> 
> - man vlc (with the docbook-to-man package, not tested)
> 
> - VLC HOWTO
> 
> Concerning the explaination of the global videolan solution, I think
> we
> should put everything concerning the VLAN solution in a separate page
> with separte documentation, and not include it in the VideoLAN HOWTO,
> because it gives the impression that VideoLAN is a very complex
> solution.
> It could be a page http://www.videolan.org/network/vlan/ with links
> to a specific doc and a download page with VLAN server, VLAN bridge,
> mini-VLANserver, etc...
> 
> Then we will have to setup the Web site so that the docs are
> automatically built in HTML, PS and PDF (we can do that easily on the
> server now that it is in Debian Woody...) every time there is a new
> commit concerning the documentation.
> 
> The problem with this solution is that we will need the 3 branchs and
> the CVS (vlc, network, vls) to build the user documentations. This
> shouldn't be a problem for the Website, but a little bit more complex
> for the guys who want to build it themselves.
> 
> I am waiting for your comments and ideas...
> 
> --
> Alexis
> --
> This is the vlc-devel mailing-list, see http://www.videolan.org/vlc/
> To unsubscribe, please read http://www.videolan.org/lists.html
> If you are in trouble, please contact <postmaster at videolan.org>
> 
-- 
This is the vlc-devel mailing-list, see http://www.videolan.org/vlc/
To unsubscribe, please read http://www.videolan.org/lists.html
If you are in trouble, please contact <postmaster at videolan.org>