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 in a Mercurial repository.

  • A script pushes the content to the actual web site, and generates the HTML pages there.

  • The XEmacs website is just another Mercurial working directory containing the latest revisions of files from the repository. Consequently all its ChangeLog files, 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 Mercurial Repository

Goto Index

The XEmacs Mercurial repository is hosted by Bitbucket and can be browsed by anyone.

Anonymous Mercurial Access

Goto Index

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

$ hg clone https://bitbucket.org/xemacs/xemacsweb
$ 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 Mercurial repository to make local changes for submission as patches or even to create a mirror site!

Mercurial Push 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 Bitbucket went live at the end of 2011.

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

hg commit -m '[A] [C] xemacsweb: fix url for master website' \
About/ChangeLog About/Website.content
hg push
  

This will only update the Mercurial repository, not the web site itself. If you want to update the web site, you'll need access to the xemacweb@gwyn.tux.org account. Then you can run:

etc/update-tux.sh
  

This will cause all master websites (i.e. http://www.xemacs.org, as of 2012-01-04) 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


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