emacs/admin/notes/www

-*- outline -*-

Copyright (C) 2013-2024 Free Software Foundation, Inc.
See the end of the file for license conditions.

NOTES FOR EMACS WWW PAGES

* Access

Anyone with write access to the Emacs code repository has the same
access to the web pages.  See <https://savannah.gnu.org/cvs/?group=emacs>
for instructions.  After you commit a change to the CVS repository,
it normally appears automatically on www.gnu.org within a few minutes.
The basic procedure is:

Initial checkout:
cvs -z3 -d:ext:<membername>@cvs.savannah.gnu.org:/web/emacs co emacs

Update from repository:
cvs up -dP

You can use Emacs's VC mode to commit files without having to worry
about knowing CVS syntax.  You may find M-x cvs-examine a useful,
more specialized, alternative to M-x vc-dir.

* Manual pages

The scripts admin/make-manuals, admin/upload-manuals can be used to do
a complete update of the on-line manual pages (e.g. after a release).

* Renaming pages, redirects

Sometimes you want to move a page to a new location.
If the old location might be referenced somewhere else, you should add
some form of redirect to the new location.  There are several ways to
do this:

** Use a refresh directive in the old file
https://www.gnu.org/server/standards/README.webmastering.html#htaccess

Change the entire contents of the old file to be something like:

<meta http-equiv="refresh" content="0; url=/software/emacs/manual/elisp.html">

I can't think of any reason to use this method.

** Use a .symlinks file
https://www.gnu.org/server/standards/README.webmastering.html#symlinks

This is really an interface to mod_rewrite rules, but it acts like
symlinks.  Remove old-page.html altogether, and create a ".symlinks"
file in the relevant directory, with contents of the form:

  # This is a comment line.
  old-page.html new-page.html

Anyone visiting old-page.html will be shown the contents of new-page.html.
Note that changes to .symlinks file are only updated periodically on
the server via cron (twice an hour?).  So there will be a delay (of up
to 30 minutes?) before you see your changes take effect.

This method is ok, but:
i) a person visiting old-page.html has no idea that the page has moved.
They still see old-page.html in their address bar.  (In other words,
the mod_rewrite rule does not use the [R] flag.)  Sometimes this is
what you want, sometimes not.

ii) it doesn't work right if the new page is in a different directory
to the old page: relative links from the visited page will break.

** Use a .htaccess file

Remove old-page.html altogether, and create a ".htaccess" file in the
relevant directory, with contents of the form:

  # This is a comment line.
  Redirect 301 /software/emacs/old-page.html /software/emacs/dir/new-page.html

Use "301" for a permanent redirection, otherwise you can omit the number.
Note that paths must (?) be relative to the top-level www.gnu.org.

I think this is the best method.  You can specify temporary or
permanent redirects, and changes go live more-or-less straight away.

This method is useful for making cross-references to non-Emacs manuals
work; see manual/.htaccess in the repository.  You only have to add a
single redirect for every given external manual, you can redirect
html_node to html_node and html_mono to html_mono.

* Why CVS?

Savannah supports other VCS, and no-one is especially attached to CVS.
Rather, CVS is the only supported mechanism for getting the changes
onto www.gnu.org.  See eg
https://lists.gnu.org/r/bug-gnulib/2012-12/msg00072.html

* CVS alternatives

To use something other than CVS, convert the web-pages CVS repository
to the other VCS, then set up a two-way sync between them.
It needs to be two-way in case eg GNU webmasters make a change to the CVS.
Ref e.g.
https://github.com/mikjo/bigitr
https://lists.gnu.org/r/savannah-hackers-public/2013-04/msg00022.html


This file is part of GNU Emacs.

GNU Emacs is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

GNU Emacs is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.