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

[Sam Hocevar]

On Wed, Jan 15, 2003, Loïc Minier wrote:

> 1/ The FAQ is ugly, it needs another format. SGML is okay.

   Agreed.

> 2/ The developers doc is in VLC's CVS, which means it is tarballed and
>    packaged automatically (read: uselessly duplicated and downloaded).

   Which packages are you talking about? I don't know of any binary vlc
shipped with the developer documentation. And the fact that it _can_ be 
built into an additional package is a positive point IMHO.

   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.

> 3/ Most of our common docs are stored in the website's CVS.

   This is true.
   
> 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.

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

>  I propose one of the following two options:
> 
> a/ - Create a vlc-doc/ module for all VLC related doc (HowTo, developer,
>      FAQ, etc.), and - on the same model - vls-doc/.
> 
>    - Create another pub-doc/ module for all the other docs.
> 
> b/ Create a pub-doc/ containing all the above mentionned docs.
> 
>    This solves the first 4 problems

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

>  but requires some redesign of the packaging scheme. The fifth problem
> is minor and might be solved using branches in the new modules.

   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.

   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.

>    This solution seems similar to other big projects, what do you think?

   While I agree generic documentation doesn't have its placein the
software modules, I don't see the point of creating new CVS modules at
all given the current situation.

Regards,
-- 
Sam.
-- 
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>