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

[Sam Hocevar]

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

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

   Those users don't even use tarballs. Tarballs account for less than
10% of the downloads. And no one will ever complain about documentation
being shipped with the tarballs, while it's sooooo much handier to have
it together with the code.

>  And it changes less often than
>  the sources, it can mostly be regarded as "static".

   I don't like this shortcut. It's changing less often, that's all. It
still needs to remain up-to-date.

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

   One simple example: http://test.videolan.org/vlc/features.html,
filling this table is definitely a developer's job. Why should we deny
developers the possibility to update the website? Some projects go
even further and have their whole website managed by a Wiki (SDLperl).

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

   .sam! HTML files in the website are the content itself.

> >    By switching to a doxygen-style documentation.
>   [...]
>    Or are you thinking VLC's doc will be entirely written in doxygen?

   Yep. Developer documentation, that is.

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

   If by "storing" you mean you mean "have a generated plaintext version
in the CVS", then I agree.

   If you mean generating a plaintext version that is then distributed
to the users is ugly, let me totally disagree. A plaintext FAQ is very
nice. Do a "locate '/usr/share/doc/*/FAQ*'" on your system, and see how
many of them are in plain-text. Some of them definitely look generated
to me, and gnupg's is really cool.

>  - storing the SGML version forces the user to have the appropriate
>    tools which might be quite difficult,

   Again this will depend on what you mean by "storing". But since we
can convert SGML to almost everything including uuencoded PDF, we can
distribute whatever we want to the user.

> and it also complicates packaging.

   Given the amount of tools needed to build VLC, I don't think anyone
will notice we added one. :-)
   
>  Since mostly developers are concerned by the CVS, I was in the trend of
>  having only developers-interesting files in VLC's CVS.

   The FAQ is definitely useful to developers. And sections such as 1.1,
1.6, 1.7 or 1.11 are to be kept up-to-date by developers.

   And it has probably been argued for ages, but I also think the VLC
user guide belongs to the VLC CVS.

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

   No I don't. Why?

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

   I meant it's a good thing to have the FAQ in the VLC CVS because it
makes it easier for the packagers to ship VLC with its FAQ.

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>