XEmacs -- Emacs: The Next Generation
English
German
Japanese
America
Asia
Australia
Europe
 
     Searching XEmacs
Quick Links About XEmacs Getting XEmacs Customizing XEmacs Troubleshooting XEmacs Developing XEmacs
      

The Multiplying XEmacs Website

Goto Index

The site is currently hosted by Tux.Org Logo.

What may be overlooked is that it also lives on many computers of developers around the world. That's what I call a multiplying website :-)

This website started out as a copy of the XEmacs site hosted by tux.org. Here is a list of key features the new site provides:

  • All site content is under CVS control.

  • CVS commits update all website mirrors automatically.

  • The XEmacs website is just another CVS working directory containing the latest revisions of files from the repository. Consequently all its ChangeLog files, .cvsignore files, genpage .content files, perl scripts, emacs-lisp files are also available via the website.

  • HTML document changes are validated against their DTD automatically.

  • genpage eases maintenance of a consistent look.

  • All intra-site links are relative to allow site mirroring and link-testing in developers' working directories.

  • Website development model is fully in line with the XEmacs development model.

  • Site update logs may also be available via HTTP, depending on the update method of the particular web-mirror you're visiting.


XEmacs Website CVS Repository

Goto Index

The XEmacs Website repository is hosted by Alioth.debian.org and can be browsed by anyone.

Anonymous CVS Access

Goto Index

Sources can be checked out into a local working directory very easily and anonymously too:

$ cvs -d :pserver:anonymous@cvs.alioth.debian.org:/cvsroot/xemacs login
Logging in to :pserver:anonymous@cvs.alioth.debian.org:2401/cvsroot/xemacs
CVS password:<press Enter or RETURN key>

$ cvs -f -z3 -d :pserver:anonymous@cvs.alioth.debian.org:/cvsroot/xemacs \
      checkout -P xemacsweb
cvs server: Updating xemacsweb
U xemacsweb/.cvsignore
<lines deleted by Adrian>
U xemacsweb/genpage/news.themes/slashdot.gpnewstheme

$ cd xemacsweb
$ make init
ln -s FAQ faq
cd genpage; make gp
<lines deleted by Adrian>
$
  

This is enough for people without write access to the CVS repository to make local changes for submission as patches or even to create a mirror site!

CVS Commit Access via SSH

Goto Index

Developers can commit their changes (after getting approval for the patch sent to xemacs-patches@xemacs.org) to the repository directly.

The repository at Alioth.debian.org went live at the end of 2009. Following users can commit their changes to the repository themselves, as of 2009-12-05 UTC.

acs-xemacs-guest apa-guest crestani-guest
daiki-guest didier-guest jjames-guest
sperber-guest sxemacs-guest unwelcome-guest
viteno-guest

Here is an example for an actual commit. Your ssh identity will authenticate you as one of the above, if you're lucky :-)

cvs -f -z3 -d :ext:apa-guest@cvs.alioth.debian.org:/cvsroot/xemacs \
commit -m '[A] [C] xemacsweb: fix url for master website' \
About/ChangeLog About/Website.content
**** Access allowed: Personal Karma exceeds Environmental Karma.
/cvsroot/xemacs/XEmacs/xemacsweb/About/ChangeLog,v  <--  About/ChangeLog
new revision: 1.232; previous revision: 1.231
/cvsroot/xemacs/XEmacs/xemacsweb/About/Website.content,v  <--  About/Website.content
new revision: 1.74; previous revision: 1.73
Processing log script arguments...
Mailing the commit message to xemacs-cvs@xemacs.org (from xemacs-cvs@xemacs.org)
Updating XEmacs master website as xemacweb@www.xemacs.org at
2009-12-16T23:01:54+0000
  

This will cause all master websites (i.e. http://www.xemacs.org, as of 2009-12-05) to be updated and the affected files validated automatically!

The result of a website update (make all) can be viewed in a newly created log file (containing the UTC time of the commit in its name -- represented almost exactly according to ISO8601).

If you have a track record of contributing to XEmacs or its website you may request to become a website developer by E-mail to xemacs-webmaint@xemacs.org.


Automatic Website Update

Goto Index

This is performed via the shared project accounts named xemacweb@www.xemacs.org (for http://www.xemacs.org/).

Use alias web-update in any of these accounts to update the website from CVS manually, but only if the automatic update is broken.

A loginfo entry for the xemacsweb module on Alioth.debian.org currently (2009-12-05) takes care of the automatic update of www.xemacs.org, which involves a cvs update, followed by a make all run.

Please note that a failing cvs update (e.g. due to a CVS conflict) will cause make all not to be run! CVS conflicts on our master websites really need to be fixed anyway.

Commits also cause a mail message to be sent to the list xemacs-cvs@xemacs.org, which is one of the XEmacs mailing lists.


Automatic Website Validation

Goto Index

Who could better validate XEmacs documentation than the master himself: XEmacs? The strength is not so much in the completeness of validation as it is in the integration with the XEmacs/PSGML web authoring environment.

A small lisp module, xemacsweb/batch-psgml-validate.el, utilizes PSGML to validate buffers, files, or directories, according to the DTD they contain.

NB: An external validator like SP may be used additionally in the future.


Maintaining a consistent look with genpage

Goto Index

Whenever you think about changing X.html in this site, please check whether X.content exists as well. In such a case, any changes you make to X.html will be lost!

See Guidelines for Contributors for more information about creating and editing .content files.

genpage is used to give a common look to HTML content in this site by wrapping it into HTML templates. Currently the only template in use is xemacsweb/template.html. genpage is run by the xemacsweb/Makefile according to the configuration defined in xemacsweb/genpage.conf.

You may run this Makefile in your local xemacsweb working directory, provided you have XEmacs (including the PSGML package), perl5 and GNU make installed. genpage itself is found in xemacsweb/genpage/bin/genpage, but the Makefile knows that. On Windows NT you will also need to install Cygwin for the Makefile to run.

We currently use genpage version 1.0.7, imported on a vendor branch. Local changes were necessary to make it work for the XEmacs site, and to make it work on Windows NT (see xemacsweb/genpage/ChangeLog for details). These will need to be reviewed when a newer version of genpage ever gets imported.


Relative Links allow Mirroring and Off-site Testing

Goto Index

Considerable work has been done to make all links within this website relative. In particular, all uses of <base href="..."> were eliminated since they add another twist. Relative links become relative to the URL specified by <base href="...">, not relative to the location of the document they appear in.

Special consideration had to be given to xemacsweb/template.html. This genpage template is used to provide a consistent look for the XEmacs site. It wraps all HTML content of .content files in the xemacsweb directory hierarchy. Any links template.html itself contains must be expanded relative to the directory of the content file. This has been implemented by use of the relPath genpage recipe.


Guidelines for Contributors

Goto Index

These rules serve the purpose of minimizing work and accelerating the learning curve for contributors.

The goal is to provide a high-quality, consistent website, showing off the power of XEmacs and its contributors.

NB: Expect the rules to evolve as they get reviewed by contributors. These just came in handy while I moved the content over from www.xemacs.org -- Adrian.

If you want to follow the discussions going on about this website you should subscribe yourself to the XEmacs Web Maintainers <xemacs-webmaint@xemacs.org> list by sending a request to xemacs-webmaint-request@xemacs.org with the word subscribe being the body of the message. This mailing list isn't archived anywhere currently.


Create .content files for new documentation

Goto Index

All new documents should be .content files to be processed by genpage. Just create the new file in xemacsweb or any of its sub-directories and run make all in the top-level directory (xemacsweb). This will generate a .html file by the same name and validate it using XEmacs/PSGML.

Here is what a minimal .content file looks like:

%title%
Title of Your Document
%author%
Your Name
%main%
Any text including HTML tags.  This text will be embedded in the
specified genpage template.  It is equivalent to the contents of the
<body>...</body> section of a corresponding HTML
document.

When you need to avoid substitution of genpage content tags in .content files (like I did in the table above) you may use the following trick:

<!-- _GP_ qq{%title%} -->
  

This genpage command returns the string-quoted genpage content tag as a string.


Generate .content files from existing .html documents

Goto Index

Use xemacsweb/html2content.pl to convert all .html files in a specified directory (recursively) to .content files. Existing .content files will not be overwritten.


Editing .content files in xml-mode with XEmacs/PSGML

Goto Index

This is the environment of choice for editing XEmacs website content.

Add following SGML comment block to the end of your .content file, so that PSGML will be configured correctly to markup and indent the file.

<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:("../template.html" "html" "body" "table" "tr" "td")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->

You'll have to manually adjust the relative path to the appropriate genpage template in sgml-parent-document.

XEmacs/PSGML is also used by the automated process which validates all documents committed to the CVS repository.


Use lower-case HTML tags

Goto Index

This is in preparation of a possible future migration to XML.


Use relative links wherever possible

Goto Index

This makes site mirroring a free gift and allows developers to test intra-site links in their private working directories off-site. Absolute links have to be used for resources which are not part of the xemacsweb CVS module and not available on all XEmacs website mirrors (e.g. Mailing list archives).


Use logical vs. physical markup

Goto Index

It is a HTML authoring commandment to prefer logical markups like <blockquote>

blockquote
</blockquote>, <strong>strong</strong>, <cite>cite</cite>, <samp>samp</samp> over physical markup like <br>
linebreak
<br>, <b>bold</b>, <i>italic</i>, or <tt>teletype</tt>.

Use <pre>

Retrieving newsgroup: nnml:xemacs-beta...
Fetching headers for nnml:xemacs-beta...
Fetching headers for nnml:xemacs-beta...done
Suppressing duplicates...
Suppressing duplicates...done
Generating summary...
Generating summary...done
Decoding base64...
Decoding base64... done

</pre> to include long runs of program output like error message logs or backtraces. Don't forget to quote HTML special characters in such excerpts! In XEmacs this can be easily done with

M-x html-quote-region

Use qq{string}, not "string" in genpage commands

Goto Index

All genpage commands (as opposed to genpage content tags) are embedded in HTML comments. Whenever these commands are embedded inside an HTML attribute, embedded "s will produce an HTML validation error.

Therefor, please use

<a href="<!-- _GP_ relPath(qq{Develop/devTeam.html}) -->">...

instead of

<a href="<!-- _GP_ relPath("Develop/devTeam.html") -->">...

Adding Release Announcements

Goto Index

This step has been automated for the Stable and Beta XEmacs development branches. See function release-mail-to-html in xemacsweb/release-mail-to-html.el. A new .content file can be auto-generated by running

The subject line and body content has to comply with the format agreed upon between the XEmacs Release Engineers. See xemacs-beta and xemacs-review for details.

M-x release-mail-to-html

Specify the name of the buffer containing a mail like this

From: XEmacs Release Engineer <martin@xemacs.org>
Subject: XEmacs 21.2.36 is released.
To: XEmacs Beta Test <xemacs-beta@xemacs.org>
Date: Wed, 4 Oct 2000 19:45:46 +0900 (JST)
Message-ID: <14811.2650.453628.696815@mule.m17n.org>
Reply-To: martin@xemacs.org

C++ compiles are broken in this beta.  I plan to have them working
again in the next one, when we change Extbyte to be plain "char"
instead of "unsigned char".

Brief summary of changes to 21.2.36 "Notus"
...

from the XEmacs Release Engineer.

Save the buffer (automatically named release-number.content) in xemacsweb/Releases.

Add references to this new files in xemacsweb/index.content and xemacsweb/Releases/index.content.

Add the newly created xemacsweb/Releases/release-number.content file to CVS and commit it together with the other modified files.


Document Index


Adrian Aichner
 
 

Conform with <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Automatically validated by PSGML