[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Helping with the webpages/documentation
Helping with the webpages/documentation
Thu, 23 Oct 2003 13:31:13 +0200
[I tried to send this yesterday, but apparently it didn't arrive on the
list. If it did arrive and you now get a duplicate my apologies. The
original version explained that I had some internet connectivity
problems. I am happy that those are solved now. New info, not in the
original message is in brackets.]
Since people care about what we publish at our project website I thought
it was a good idea to forward the following information (attached) on
how the documentation and webpages are build to the list. I send this to
Patrik already, who wanted to help spicing up the pages a bit, and who
now seems to actually enjoy WML, so please coordinate with him.
On suggesting/linking to non-free software (since the topic came up).
We want GNU Classpath (and everything found through the gnu.org website)
to enable people to be free from any control on how they can use or
create java-like systems. We really want it to be so perfect that people
can be sure that if they follow advice/links on gnu.org to certain
software packages they will get free software, which they can use,
study, modify and distribute however they want. That is a high standard,
but our users will appreciate it when they know they can depend on that.
On the specific case of org.omg and jgss. I think Stuart is right
that it is better to not point people to these implementations as long
as we cannot guarantee that we are suggesting something which is free.
But please lets at the same time try to find solutions for our users. It
would be great if someone could take a quick look at JacORB to see if
that is something we can suggest to people looking for free software.
And references to standards that can help with implementing replacements
(such as RFCs) should of course go into the Hacking Guide.
[Thanks to Stephen Crawley for the the rundown of how OMG works and what
their priorities are. Clearly their priorities are not our priorities,
but I hope we can work something out so that we can provide a free
software implementation of the Corba standard. If Brian can help me with
his contacts at OMG, I am happy to help negotiate something.]
The above is not meant as unhelpful religious zealotry, disalowing
choice or declaring things illegal. It is meant as a practical guideline
to make sure that we empower our users which come to gnu.org for
information on Free Software. There are enough other resourcesoin
non-free proprietary things, which I think everybody can already readily
find. No need for us to do that. But if people really think it is that
impractical then having a www.classpath.org which is not directly
affiliated with www.gnu.org might actually be a good idea. It would make
it much more clear what kind of things people can expect to find on the
"official" http://www.gnu.org/software/classpath/ page and what other
kind resources are available. But I hope it will not be necessary.
[Now, with all that said, please take a look at how the documentation
and webpages are actually build. Instructions attached at the end.]
[Documentation and webpages]
If you want to work on helping updating/maintaining the webpages
(http://www.gnu.org/software/classpath/) then you start by looking at
the doc/www.gnu.org/ directory in the main classpath cvs module. The
first thing todo would probably be to update the README file in there to
make it a bit more friendly for other people to contribute. For example
adding some of the rest of this email after you verified I don't talk
nonsense would be nice :).
Currently the Makefile uses two tools for generating the webpages:
- WML: http://thewml.org/
Debian package (wml)
- texi2html: http://texi2html.cvshome.org/
Debian package (texi2html)
The manuals should be written in texinfo whenever possible since that
gives us the most flexibility to generate different formats and it is
the GNU standard for creating documentation so it fits in the best with
the rest of the system (http://www.gnu.org/software/texinfo/ has lots of
documentation and guidelines for GNU manuals).
WML is just a nice thing to quickly create smaller webpages, and I would
recommend its use unless someone comes up with a really better way to
easily create those pages.
When you have these tools installed then just typing make in
doc/www.gnu.org/ should do all the magic needed to convert the texinfo
manuals (doc/hacking.texinfo and doc/vmintegration.texinfo) and the wml
pages into html.
Transfering the generated pages to the actual www.gnu.org machine is
done by copying the generated files to the GNU Classpath webpage
repository (see https://savannah.gnu.org/cvs/?group=classpath).
All other support files that must be present on the webserver can also
be found in that CVS module.
There is a convenience make target 'publish' that helps with that.
Guidelines for www.gnu.org(/software) content can be found at:
Some hints and tips (symbolic links and generating timestamps) can be
learned from: http://www.gnu.org/server/standards/README.html
There is also a mechanism to generate the api documentation using gjdoc
(only available from cp-tools in CVS I believe) when configuring with
--enable-gjdoc. This will then generate HTML files in doc/api/html.
There is currently no simple way to upload these to www.gnu.org though.
And generating the correct copyright/license statement for them is not a
completely solved problem, although it shouldn't be that hard.