\input texinfo @c -*- Texinfo -*-
@c %**start of header
@setfilename publish.info
@settitle @code{Web and documentation publishing Guide}
@setchapternewpage odd
@c %**end of header
@set RCSID $Id: publish.en.texi 1796 2004-10-17 20:41:43Z wikifr $
@set VERSION 1.0
@c Combine the variable and function indices:
@syncodeindex vr fn
@c Combine the program and concept indices:
@syncodeindex pg cp
@titlepage
@title Web and documentation publishing Guide
@subtitle Information specific to FSF France machines
@subtitle @code{Web and documentation publishing Guide} Version @value{VERSION}
@author Loic Dachary, Rodolphe Quiedeville, updated by Mathieu Roy
@page
@vskip 0pt plus 1filll
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@end titlepage
@page
@ifnottex
@node Top, Introduction, (dir), (dir)
@top Sysadmin France
This document is for webmasters and users of FSF France machines. It may
contain useful bits of informations outside this context.
@end ifnottex
@menu
* Introduction::
* XML and interoperability::
* DocBook Quick Start::
* Web::
* Private Data::
* Concept Index::
* Name Index::
@detailmenu
--- The Detailed Node Listing ---
DocBook Quick Start
* DocBook packages::
* DocBook formating::
Web
* Overview::
* Virtual Hosts::
* Editing the Web::
* Separate layout and content::
* Publishing news::
* Update from CVS::
* Immediate Update::
* Coposys::
Separate layout and content
* XHTML and XSLT Quick Start::
* XSLT processors::
* Writing XHTML content::
* XSL and generated HTML::
* Writing XSL files::
Coposys
* Intro::
* Configuration::
* Install::
* Apache configuration::
* File permissions and owners::
* Crontab::
* HTML design::
@end detailmenu
@end menu
@node Introduction, XML and interoperability, Top, Top
@chapter Introduction
In many aspects, the GNU way of doing things needs to be
improved. When this is the case the idea is to coordinate with the GNU
volunteers in charge of a specific aspect in order to improve the
system. Doing so is a not as hard as contributing to a software. It
may sometime be frustrating to stick to the GNU policy because it is
quicker to get a nice result by inventing something completely
new. The Web is probably the most striking example. However, since we
claim to be part of the GNU project we don't really have the option to
fork something of our own and leave the GNU project behind. Even if it
means that we will go slower, coordination with and improvement of the
GNU project as a whole should be our goal.
Close cooperation with the GNU project also makes some things a lot
easier. The account creation process, the management of the HTML tree
from CVS, the DNS hosting, mailing lists etc. are facilities we do not
need to re-implement. When installing something entirely new on the
GNU machines located in France, it is important to send a note on the
relevant mailing lists in advance. This prevents possible duplication
of the effort and greatly increases the chances that the GNU project
will be able to re-use the new facility.
Reference documents describing the GNU environment are
@uref{http://www.gnu.org/server/standards/,,standards} for webmaster
information, @file{fencepost.gnu.org:/gd/gnuorg/sysadmin/sysadmin.texi}
for system administration information.
For usage of the project hosting facility, see Gna! documentation.
@node XML and interoperability, DocBook Quick Start, Introduction, Top
@chapter XML and interoperability
When publishing content or building a database for specific purposes (contact
database, task lists, account information, permissions etc.) it is of the
outermost importance to choose a data format that allows other programs
to re-use the database and your own program to import databases from other
programs.
Using XML for that purpose is only half of the answer. XML will merely
prevent you to write a parser to read XML files and save you from the
pitfall of inventing yet another data format. It says nothing about the
semantic of the tags you decided to use. The harder part is to define
the semantic associated with an XML file. For instance,
@uref{http://www.docbook.org/,,DocBook} uses XML but the core of the
work was to define what each tag means and make sure it covers all
possible needs. It tooks years and is not finished yet. Inventing a new
semantic for a given purpose is not something that should be undertaken
lightly.
In some cases there already exists a semantic that fits your needs. Even
if it's not an established standard
(@uref{http://groups.yahoo.com/group/rss-dev/files/specification.html,,RSS}
is a widely spread de-facto standard) it will save you the effort to invent
something completely new. You may even be able to join the group that works
on this semantic to enhance it if needs be. There are some DTD repositories
that can help you find out if something exists:
@itemize @bullet
@item @uref{http://www.xml.com/pub/rg/DTDs,,XML.com DTD}
@item @uref{http://www.rosettanet.org/rosettanet/Rooms/DisplayPages/LayoutInitial?Container=com.webridge.entity.Entity%5BOID%5B6EDB5FE87F69D411BD84009027E33DD8%5D%5D,,RosettaNet}
@item @uref{http://www.hr-xml.org/schemas/dtd/,hr-xml.org}
@item @uref{http://www.schema.net/,,Schema.net}
@item @uref{http://registry.xml.org:2020/repository/ui/searchResults.jsp?qall=dtd,,XML.org}
@item @uref{http://www.openapplications.org/_vti_bin/shtml.exe/xml/loadform.htm,,Open Applications Group}
@item @uref{http://www.lisa.org/tmx/tmx.htm,,Translation Memory eXchange}
@item @uref{http://www.docuverse.com/xlf/index.html,,Extensible Log Format}
@end itemize
When the data format is chosen, choosing or writing the programs that provide
a given service is driven by this choice. If an application exists that does
not support the format chosen, it's fairly reasonable to write a small program
that translate the data format into the application specific data and vice
versa. The advantages of doing this are:
@itemize @bullet
@item If a new, better program becomes available and you can switch to it using
the chosen data format do dump/reload the data.
@item If you contribute the export/import program to the developers of the
program they are likely to accept it because it's based on a standard.
@item If you want to display static HTML pages from the XML export, XSLT
allows to do this in a fairly simple way.
@end itemize
@node DocBook Quick Start, Web, XML and interoperability, Top
@chapter DocBook Quick Start
@cindex DocBook usage
@cindex XSLT and DocBook
@cindex DSSSL not used for DocBook
@cindex DocBook using unstable or testing
When using a debian unstable distribution it is fairly easy to write and
format @uref{http://www.docbook.org/,,DocBook} documentation with few
manual operations. However, one has to know the shortest path otherwise
it quickly turns into a nightmare. An
@uref{http://www.w3c.org/TR/xslt,,XSLT} based (as opposed to DSSSL) set
of packages and commands is proposed here, assuming you are running
unstable. It will also works at the date of this writing (October 2001)
if you're running testing but will require to install the packages
recommended here from unstable.
@menu
* DocBook packages::
* DocBook formating::
@end menu
@node DocBook packages, DocBook formating, DocBook Quick Start, DocBook Quick Start
@section DocBook packages
@cindex xsltproc
@cindex passivetex
@cindex xmltex
@cindex DocBook packages
On GNU/Linux Debian unstable install the following packages:
@example
apt-get install xsltproc
apt-get install docbook-xsl
apt-get install xmltex
@end example
Install passivetex as found at @url{http://users.ox.ac.uk/~rahtz/passivetex/}.
@example
cd /usr/share/texmf/tex/latex/
mkdir passivetex
cd passivetex
unzip /tmp/passivetex.zip
cd /usr/share/texmf/tex/xmltex/base
pdftex -ini "&pdflatex" pdfxmltex.ini
fmtutil --missing
texlinks
texhash
@end example
Finally, the global memory size parameters of TeX must be increased.
If formating fails, check for @code{exceeded} errors and increase
the corresponding parameter. Some sample values are available at
@url{http://users.ox.ac.uk/~rahtz/passivetex/}.
@example
*** /etc/texmf/texmf.cnf.~1~ Sun Sep 16 23:06:18 2001
--- /etc/texmf/texmf.cnf Wed Oct 17 15:37:48 2001
***************
*** 398,409 ****
% Extra space for the hash table of control sequences (which allows 10K
% names as distributed).
hash_extra.context = 25000
! hash_extra = 0
% Max number of characters in all strings, including all error messages,
% help texts, font names, control sequences. These values apply to TeX and MP.
pool_size.context = 750000
! pool_size = 125000
% Minimum pool space after TeX/MP's own strings; must be at least
% 25000 less than pool_size, but doesn't need to be nearly that large.
string_vacancies.context = 45000
--- 398,409 ----
% Extra space for the hash table of control sequences (which allows 10K
% names as distributed).
hash_extra.context = 25000
! hash_extra = 50000
% Max number of characters in all strings, including all error messages,
% help texts, font names, control sequences. These values apply to TeX and MP.
pool_size.context = 750000
! pool_size = 1250000
% Minimum pool space after TeX/MP's own strings; must be at least
% 25000 less than pool_size, but doesn't need to be nearly that large.
string_vacancies.context = 45000
***************
*** 442,448 ****
param_size.context = 1500
param_size = 500 % simultaneous macro parameters
save_size.context = 5000
! save_size = 4000 % for saving values outside current group
stack_size.context = 1500
stack_size = 300 % simultaneous input sources
--- 442,448 ----
param_size.context = 1500
param_size = 500 % simultaneous macro parameters
save_size.context = 5000
! save_size = 10000 % for saving values outside current group
stack_size.context = 1500
stack_size = 300 % simultaneous input sources
@end example
@node DocBook formating, , DocBook packages, DocBook Quick Start
@section DocBook formating
Formating DocBook in html or pdf can be done from the following
Makefile sample.
@example
all: sample.html sample.pdf
clean:
rm -f sample.aux sample.fo sample.log sample.out \
sample.html sample.pdf
sample.html: sample.xml custom_html.xsl
export SGML_CATALOG_FILES=/usr/lib/sgml/catalog ; \
xsltproc \
--catalogs \
-o sample.html \
custom_html.xsl sample.xml
sample.pdf: sample.xml custom_fo.xsl
export SGML_CATALOG_FILES=/usr/lib/sgml/catalog ; \
xsltproc \
--catalogs \
-o sample.fo \
custom_fo.xsl sample.xml
pdflatex "&pdfxmltex" sample.fo
@end example
@node Web, Private Data, DocBook Quick Start, Top
@chapter Web
@menu
* Overview::
* Virtual Hosts::
* Editing the Web::
* Separate layout and content::
* Publishing news::
* Update from CVS::
* Immediate Update::
* Coposys::
@end menu
@node Overview, Virtual Hosts, Web, Web
@section Overview
The FSF France web sites are stored in CVS on the Gna! machines. They
can be edited from there and fsffrance.org has a local copy
of all the pages that are updated three times per day. The primary
purpose of the fsffrance.org machine is to host the FSF France web site,
data and programs. However every web site related to the FSF France
projects and friends of the FSF France are invited to use the machine
for web hosting if they need it.
@node Virtual Hosts, Editing the Web, Overview, Web
@section Virtual Hosts
The @file{/etc/apache/httpd.conf} was configured with virtual hosts. It
handles the following domain names:
@table @samp
@item fsffrance.org
with a document root at @file{/storage/www/www.fsffrance.org/htdocs}.
@end table
All new domains should use a similar policy, that will help keeping
things simple.
@node Editing the Web, Separate layout and content, Virtual Hosts, Web
@section Editing the Web
@cindex fsfe project
@cindex edit fsffrance.org
All users registered in the
@uref{http://gna.org/projects/fsffrance/,,FSF France www management}
project can edit the HTML repository using CVS/SSH. Instructions on how to do so can
be found on Gna!
The modified files will be updated on fsffrance.org within one
day (normally less than that).
The pages are stored in @code{.xhtml} files and formatted automatically
to @code{.html} files. @ref{XHTML and XSLT Quick Start} will tell you
how to deal with this within seconds.
@node Separate layout and content, Publishing news, Editing the Web, Web
@section Separate layout and content
@cindex SSI
It is convenient to separate the layout of an HTML page from the actual
content. It prevents duplicating the menus in each page and allows to
have a nice display without the burden of fixing it in every page when
something needs fixing. Using SSI (Server Side Includes) is a solution
to this problem but it has the disadvantage that it requires from
web server displaying the pages to have this feature enabled, which is
not always the case.
@cindex XSLT
@cindex XHTML
We chose to use an @uref{http://www.w3c.org/TR/xslt,,XSLT}
processor to separate the content from the layout. An XSLT processor
provides something similar to a C preprocessor but is applied to XML
files. The content of the pages are written in
@uref{http://www.w3.org/TR/xhtml1,,XHTML}, which is a slightly
different form of HTML that makes it XML compliant. The layout of the
pages is stored in XSL files and the XSLT processor merges the two to
produce an HTML page that will be used for display.
@example
XSL file ----\
=> XSLT processor ----> HTML file
XHTML file ----/
@end example
We chose to use XSL rather than any other method because it is
a widely accepted standard and that Free Software tools are available
everywhere that implement it. There are many possible uses of XSL but
this chapter only focuses on using it to separate the layout of a
web site from it's content.
@menu
* XHTML and XSLT Quick Start::
* XSLT processors::
* Writing XHTML content::
* XSL and generated HTML::
* Writing XSL files::
@end menu
@node XHTML and XSLT Quick Start, XSLT processors, Separate layout and content, Separate layout and content
@subsection XHTML and XSLT Quick Start
@cindex edit .xhtml files
@cindex .xhtml files editing
@cindex XHTML and XSLT quick start
@cindex XSLT and XHTML quick start
Assuming you're facing a directory that contains a mixture of
@code{.xhtml}, @code{.html} and/or @code{.xsl} files and you just
want to contribute content without actually understanding what all
this about, here is what you should do:
@itemize @bullet
@item Modify the @code{.xhtml} file, not the generated @code{.html} file.
@item If you want to create a new file, create it with the @code{.xhtml}
extension. Copy a @file{boilerplate.xhtml} from @uref{http://fsffrance.org/boilerplate.xhtml,,somewhere} or copy and modify a @code{.xhtml} file
in the same directory.
@item To see the resulting HTML file, look for a Makefile in the directory
or the upper directories that recursively walk the tree to format XHTML
files into HTML files. If a grep @code{sabcmd} or @code{xsltproc} on a
Makefile finds something, you probably found the good one. Run @code{make
all} and look at the generated HTML file with your web browser.
@item To add a menu entry, edit the XSL file that ends with the @code{.xsl}
extension. It should contain the menu entries: that's why they are
created in the first place. Although the syntax of this file may not be
familiar, the menu entries themselves are written in plain XHTML.
@cindex your own XSL files
@cindex XSL files of your own
@item To re-use existing XSL files for your own web pages do the following
@example
#
# Make sure you have the sablotron XSLT processor
#
apt-get install sablotron
#
# Get the XSL files
#
wget http://fsffrance.org/navigation.fr.xsl
wget http://fsffrance.org/fsfe-fr.xsl
#
# Get the Makefile
#
wget -O Makefile http://fsffrance.org/Makefile.sample
#
# Get the boilerplate
#
wget http://fsffrance.org/boilerplate.fr.xhtml
#
# edit fsfe-fr.xsl and remove all references to navigation.*.xsl other
# than navigation.en.xsl.
#
# Build the boilerplate.fr.html file
#
make all
#
# View boilerplate.fr.html with a web browser and start customizing
#
@end example
If you are using an Red Hat distribution, to install
@uref{http://www.gingerall.com/charlie-bin/get/webGA/act/download.act,,sablotron},
you need first install
@uref{http://sourceforge.net/projects/expat,,expat} :
@example
# get expat's RPM file
ftp speakeasy.rpmfind.net
user ftp
pass
cd /linux/C/redhat/7.1/en/os/i386/RedHat/RPMS
get expat-1.95.1-1.i386.rpm
#
# install expat
rpm -i expat-1.95.1-1.i386.rpm
#
# get sablotron
wget http://www.gingerall.com/perl/rd?url=sablot/sablotron-0.52-1.i386.rpm
# install sablotron
rpm -i sablotron-0.52-1.i386.rpm
#
@end example
@end itemize
@node XSLT processors, Writing XHTML content, XHTML and XSLT Quick Start, Separate layout and content
@subsection XSLT processors
There are many XSLT processors. We recommend the following two:
@itemize @bullet
@cindex sabcmd
@cindex sablotron
@item @uref{http://www.gingerall.com/charlie-bin/get/webGA/act/download.act,,sablotron}
@cindex libxslt
@cindex xsltproc
@item @uref{http://www.xmlsoft.org/,,libxslt}
@end itemize
@node Writing XHTML content, XSL and generated HTML, XSLT processors, Separate layout and content
@subsection Writing XHTML content
@cindex XHTML rules
The content of the web site is written in XHTML files that have
the @code{.xhtml} extension. The XHTML looks like a regular HTML
file, you don't have to learn anything new. Taking an existing HTML
file and converting it to XHTML is simple. You only have to take
care of the following:
@itemize @bullet
@item Add the following at the beginning of the file:
@example
@end example
This declaration says that your file is in XHTML and that it contains
@code{iso-8859-1} characters.
@item Always close opening tags or the XSLT processor will bark. If
you want to use a single tag, end it with a />.
@example