admin/notes/www

   1 -*- outline -*-
   2
   3 Copyright (C) 2013-2024 Free Software Foundation, Inc.
   4 See the end of the file for license conditions.
   5
   6 NOTES FOR EMACS WWW PAGES
   7
   8 * Access
   9
  10 Anyone with write access to the Emacs code repository has the same
  11 access to the web pages.  See <https://savannah.gnu.org/cvs/?group=emacs>
  12 for instructions.  After you commit a change to the CVS repository,
  13 it normally appears automatically on www.gnu.org within a few minutes.
  14 The basic procedure is:
  15
  16 Initial checkout:
  17 cvs -z3 -d:ext:<membername>@cvs.savannah.gnu.org:/web/emacs co emacs
  18
  19 Update from repository:
  20 cvs up -dP
  21
  22 You can use Emacs's VC mode to commit files without having to worry
  23 about knowing CVS syntax.  You may find M-x cvs-examine a useful,
  24 more specialized, alternative to M-x vc-dir.
  25
  26 * Manual pages
  27
  28 The scripts admin/make-manuals, admin/upload-manuals can be used to do
  29 a complete update of the on-line manual pages (e.g. after a release).
  30
  31 * Renaming pages, redirects
  32
  33 Sometimes you want to move a page to a new location.
  34 If the old location might be referenced somewhere else, you should add
  35 some form of redirect to the new location.  There are several ways to
  36 do this:
  37
  38 ** Use a refresh directive in the old file
  39 https://www.gnu.org/server/standards/README.webmastering.html#htaccess
  40
  41 Change the entire contents of the old file to be something like:
  42
  43 <meta http-equiv="refresh" content="0; url=/software/emacs/manual/elisp.html">
  44
  45 I can't think of any reason to use this method.
  46
  47 ** Use a .symlinks file
  48 https://www.gnu.org/server/standards/README.webmastering.html#symlinks
  49
  50 This is really an interface to mod_rewrite rules, but it acts like
  51 symlinks.  Remove old-page.html altogether, and create a ".symlinks"
  52 file in the relevant directory, with contents of the form:
  53
  54   # This is a comment line.
  55   old-page.html new-page.html
  56
  57 Anyone visiting old-page.html will be shown the contents of new-page.html.
  58 Note that changes to .symlinks file are only updated periodically on
  59 the server via cron (twice an hour?).  So there will be a delay (of up
  60 to 30 minutes?) before you see your changes take effect.
  61
  62 This method is ok, but:
  63 i) a person visiting old-page.html has no idea that the page has moved.
  64 They still see old-page.html in their address bar.  (In other words,
  65 the mod_rewrite rule does not use the [R] flag.)  Sometimes this is
  66 what you want, sometimes not.
  67
  68 ii) it doesn't work right if the new page is in a different directory
  69 to the old page: relative links from the visited page will break.
  70
  71 ** Use a .htaccess file
  72
  73 Remove old-page.html altogether, and create a ".htaccess" file in the
  74 relevant directory, with contents of the form:
  75
  76   # This is a comment line.
  77   Redirect 301 /software/emacs/old-page.html /software/emacs/dir/new-page.html
  78
  79 Use "301" for a permanent redirection, otherwise you can omit the number.
  80 Note that paths must (?) be relative to the top-level www.gnu.org.
  81
  82 I think this is the best method.  You can specify temporary or
  83 permanent redirects, and changes go live more-or-less straight away.
  84
  85 This method is useful for making cross-references to non-Emacs manuals
  86 work; see manual/.htaccess in the repository.  You only have to add a
  87 single redirect for every given external manual, you can redirect
  88 html_node to hmtl_node and html_mono to html_mono.
  89
  90 * Why CVS?
  91
  92 Savannah supports other VCS, and no-one is especially attached to CVS.
  93 Rather, CVS is the only supported mechanism for getting the changes
  94 onto www.gnu.org.  See eg
  95 https://lists.gnu.org/r/bug-gnulib/2012-12/msg00072.html
  96
  97 * CVS alternatives
  98
  99 To use something other than CVS, convert the web-pages CVS repository
 100 to the other VCS, then set up a two-way sync between them.
 101 It needs to be two-way in case eg GNU webmasters make a change to the CVS.
 102 Ref e.g.
 103 https://github.com/mikjo/bigitr
 104 https://lists.gnu.org/r/savannah-hackers-public/2013-04/msg00022.html
 105
 106 \f
 107 This file is part of GNU Emacs.
 108
 109 GNU Emacs is free software: you can redistribute it and/or modify
 110 it under the terms of the GNU General Public License as published by
 111 the Free Software Foundation, either version 3 of the License, or
 112 (at your option) any later version.
 113
 114 GNU Emacs is distributed in the hope that it will be useful,
 115 but WITHOUT ANY WARRANTY; without even the implied warranty of
 116 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 117 GNU General Public License for more details.
 118
 119 You should have received a copy of the GNU General Public License
 120 along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.