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 |
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 |
In reply to this post by Andreas Jellinghaus-2
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 |
In reply to this post by Andreas Jellinghaus-2
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 |
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 |
Free forum by Nabble | Edit this page |