documentation management [u]

[Andreas Jellinghaus-2]

I'm rethinking what we should do with the
documentation.

This is essential for me:
 - generating documentation caused problems earlier,
   so I want to ship releases with generated documentation.
   the user should be able to use those simply, and not
   need any tools installed.
 - developers should be able to make changes without needing
   those tools, too.
 - no suprises. nobody expects commands like "make" "make install"
   "make dist" "configure" or "bootstrap" to do network connections.
   so none of those commands will for example trigger downloading
   the wiki and converting it to html.
 - "make dist" will create a tar file including documentation.

also so far the policy for code and build system was:
 - only files that cannot be generated are in svn.
 - "make maintainer-clean" will remove all files that can
   be generated, after you ran it, you have the svn files
   left, no more, no less.

the current situation breaks that rule: html documentation
is commited to svn, too. so far that wasn't much documentation,
but now we start using doxygen, so it should be more documentation
soon.

I see these choices:
 - keep it like that, i.e. manualy generate the documentation using
   scripts and add the result to svn.
 - remove the generated documentation from svn. instead have a script
   to download / generate it, similar like bootstrap, and use that one.
   that means svn would not containt and documentation. snapshots could
   still have it, as the nightly snapshot script can do these things.

also some people suggested to have the documentation generating / update
etc. stuff in the normal make process and enable it via configure options.

we already had some discussion of these parts, I'd like to read more
comments what you prefer, so we can come to some agreement and implement
it.

Regards, Andreas
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel

[Douglas de Oliveira Mendes-2]

    In my opinion, svn should not store files that can be easily
generated, like doxygen documentation or binaries. But the daily builds
should have them. Version control over these kind of files is ugly..

Douglas

Andreas Jellinghaus [c] escreveu:

>I'm rethinking what we should do with the
>documentation.
>
>This is essential for me:
> - generating documentation caused problems earlier,
>   so I want to ship releases with generated documentation.
>   the user should be able to use those simply, and not
>   need any tools installed.
> - developers should be able to make changes without needing
>   those tools, too.
> - no suprises. nobody expects commands like "make" "make install"
>   "make dist" "configure" or "bootstrap" to do network connections.
>   so none of those commands will for example trigger downloading
>   the wiki and converting it to html.
> - "make dist" will create a tar file including documentation.
>
>also so far the policy for code and build system was:
> - only files that cannot be generated are in svn.
> - "make maintainer-clean" will remove all files that can
>   be generated, after you ran it, you have the svn files
>   left, no more, no less.
>
>the current situation breaks that rule: html documentation
>is commited to svn, too. so far that wasn't much documentation,
>but now we start using doxygen, so it should be more documentation
>soon.
>
>I see these choices:
> - keep it like that, i.e. manualy generate the documentation using
>   scripts and add the result to svn.
> - remove the generated documentation from svn. instead have a script
>   to download / generate it, similar like bootstrap, and use that one.
>   that means svn would not containt and documentation. snapshots could
>   still have it, as the nightly snapshot script can do these things.
>
>also some people suggested to have the documentation generating / update
>etc. stuff in the normal make process and enable it via configure options.
>
>we already had some discussion of these parts, I'd like to read more
>comments what you prefer, so we can come to some agreement and implement
>it.
>
>Regards, Andreas
>_______________________________________________
>opensc-devel mailing list
>[hidden email]
>http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel
>
>  
>

       
       
               
_______________________________________________________
Yahoo! Acesso Gr?tis - Internet r?pida e gr?tis.
Instale o discador agora! http://br.acesso.yahoo.com/
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel

[Peter Stuge]

On Mon, Aug 29, 2005 at 07:39:59PM +0200, Andreas Jellinghaus [c] wrote:
> we already had some discussion of these parts, I'd like to read
> more comments what you prefer

I like to have documentation in the tarball. I like to have it in an
easily accessible format (nroff/txt, or worst-case html) after make,
and finally I don't like the package to depend on a number of text
processors/converters otherwise unrelated to the project.

I want libraries to either have structural and API documentation
in their tarballs, or available online. I prefer simple files in the
tarball.


//Peter
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel

[Ludovic Rousseau]

On 29/08/05, Andreas Jellinghaus [c] <[hidden email]> wrote:
> I'm rethinking what we should do with the
> documentation.
>
> This is essential for me:
>  - generating documentation caused problems earlier,
>    so I want to ship releases with generated documentation.
>    the user should be able to use those simply, and not
>    need any tools installed.

I agree

>  - developers should be able to make changes without needing
>    those tools, too.

I agree. But the generated documentation will not be up to date until
someone or something regenerate it. If the developer do not have the
tools he will not do it himself. But he may install the tools if he
wants to have an up-to-date doc.

>  - no suprises. nobody expects commands like "make" "make install"
>    "make dist" "configure" or "bootstrap" to do network connections.
>    so none of those commands will for example trigger downloading
>    the wiki and converting it to html.

I agree for "make", "make install", "configure" and bootstrap.

I do not agree for "make dist". "make dist" should be used by the
"release team" and by the cron job to create the nightly builds.
Normal users and developers should not need this. And if they really
want to run "make dist" they can install the needed tools.

>  - "make dist" will create a tar file including documentation.

I agree. And the documentation shall be up to date (regenerated with
Doxygen or a fresh wiki page copy).

> also so far the policy for code and build system was:
>  - only files that cannot be generated are in svn.

I agree.

>  - "make maintainer-clean" will remove all files that can
>    be generated, after you ran it, you have the svn files
>    left, no more, no less.

I do not agree but this is not really, really, really important :-)

> I see these choices:
>  - keep it like that, i.e. manualy generate the documentation using
>    scripts and add the result to svn.

Bad!

>  - remove the generated documentation from svn. instead have a script
>    to download / generate it, similar like bootstrap, and use that one.
>    that means svn would not containt and documentation. snapshots could
>    still have it, as the nightly snapshot script can do these things.

Snapshots will have the doc, release version will have the doc.
Developers using SVN can generate the doc themselves if they need it.
I can do it myself so it is not very difficult :-)

> also some people suggested to have the documentation generating / update
> etc. stuff in the normal make process and enable it via configure options.

Not by the normal make process. Only by "make dist".

I use "make dist" to generate an up-to-date ChangeLog.cvs file for
pcsc-lite. I never received any complaint about that.

Bye,

--
  Dr. Ludovic Rousseau
 For private mail use [hidden email] and not "big brother" Google
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel

[Andreas Jellinghaus-2]

On Tuesday 30 August 2005 13:40, Ludovic Rousseau wrote:

> I do not agree for "make dist". "make dist" should be used by the
> "release team" and by the cron job to create the nightly builds.
> Normal users and developers should not need this. And if they really
> want to run "make dist" they can install the needed tools.
>
> >  - "make dist" will create a tar file including documentation.
>
> I agree. And the documentation shall be up to date (regenerated with
> Doxygen or a fresh wiki page copy).
>
> Not by the normal make process. Only by "make dist".

...
> I use "make dist" to generate an up-to-date ChangeLog.cvs file for
> pcsc-lite. I never received any complaint about that.

ok, ok. change to do that for opensc, openct, libp11, pam_p11 and
engine_pkcs11 at http://www.opensc.org/files/wip/

if noone complains I'd like to commit all that, and port the
doxygen stuff from openct to all other projects, too.

Regards, Andreas
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel