[vlc-devel] Re: [RFC] New doc module?

[Loïc Minier]

Sam Hocevar <sam at zoy.org> - Wed, Jan 15, 2003:

>    My feeling is that the documentation is small enough to be included
> with the source tarballs. If this feeling is not shared, then we can
> build tarballs without it.

 I feel most users simply don't need it. And it changes less often than
 the sources, it can mostly be regarded as "static".


> > 4/ The website's CVS is not public (until now) and we need to give
> >    accounts for other developers to contribute doc.
>    This is not a problem at all, since developers have access to non-
> public areas.

 Why give accounts in the website's CVS? What is the relation with VLC's
 development? We could for example have the same access files for an
 hypothetical vlc-doc/ module and the vlc/ module.
   I feel mixing the website's files (which are mostly presentation of a
 content) with a part of the content itself is ugly.


> > 5/ How can we keep in sync vlc and its developer doc?
>    By switching to a doxygen-style documentation. Separating the
> developer documentation from the code is the best way to let it rot.

 Yes, doxygen is very good for this. Doxygen doc will always stay with
 the sources (if I understood doxygen correctly), which is a good
 thing. But the rest of the doc is not doxygen and it's far from being a
 small part of the whole.
   Or are you thinking VLC's doc will be entirely written in doxygen?


>    I fail to see how it solves 1/, and 2/ 3/ 4/ are not problems.

 I forgot to give my point of view on storing a FAQ in VLC's CVS:
 - storing a plaintext version which is created using another source is
   clearly ugly,
 - storing the SGML version forces the user to have the appropriate
   tools which might be quite difficult, and it also complicates
   packaging.

 Since mostly developers are concerned by the CVS, I was in the trend of
 having only developers-interesting files in VLC's CVS.


>    The fifth problem is not minor at all. I won't speak for other parts
> of VideoLAN, but as far as I am concerned, there is absolutely no way
> (read: absolutely no way) anyone will move the VLC developer documentation
> out of the VLC tree.

 Do you think developers are working with older versions of the
 documentation others than the latest one?


>    As for the FAQ, while I agree it's not very pretty, I think it's OK
> to have it in the VLC tree _because_ it can be shipped with VLC.

 I don't understand what you're saying here.


-- 
lool
-- 
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>