Commits

adriana  committed 61e9e52

[xemacsweb PATCH] xemacsweb process improvements, general update <u3dj6r4hn.fsf@ecf.teradyne.com>

  • Participants
  • Parent commits cb5035f

Comments (0)

Files changed (9)

File About/ChangeLog

+2000-09-11  Adrian Aichner  <aichner@ecf.teradyne.com>
+
+	* Website.content: Document .content file structure and conversion
+	from .html files.  Add more links to documentation.
+	* created.content: Add http://dirac.ruc.dk/~gnalle/.
+
 2000-08-24  Adrian Aichner  <aichner@ecf.teradyne.com>
 
 	* Website.content: Add more info, document temporary GNU make

File About/Website.content

               provides:</p>
             <ul>
               <li><p>All site content is under CVS control</p></li>
-              <li><p>CVS commits update the website automatically</p></li>
+              <li><p>CVS commits update the website
+                  automatically</p></li>
               <li><p>HTML document changes are validated against their
                   DTD automatically</p></li>
-              <li><p>genpage eases maintenance of a consistent look</p></li>
+              <li><p><a href="../genpage/www/index.html">genpage</a>
+                  eases maintenance of a consistent look</p></li>
               <li><p>All intra-site links are relative to allow site
                   mirroring and link-testing in developers working
                   directories</p></li>
               <li><p>Website development model is fully in line with
                   XEmacs development model</p></li>
               <li><p>Site update <a href="../logs/">logs</a> are
-              available via HTTP</p></li>
+                  available via HTTP</p></li>
             </ul>
             <hr>
             <h2>XEmacs <a name="XWCR">Website</a> CVS Repository</h2>
             <p><a href="#index">Goto</a> Index</p>
-            <p>
-              The XEmacs Website repository is hosted by <a
-              href="http://sourceforge.net/">SourceForge</a> and can
-              be <a
-              href="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/?cvsroot=xemacs">browsed</a>
+            <p>The XEmacs Website repository is hosted by <a href="http://sourceforge.net/">SourceForge</a> and can be
+              <a href="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/?cvsroot=xemacs">browsed</a>
               by anyone.</p>
-            <p>
-              Only developers can commit their changes to the
-              repository themselves.  Here is the <a
-              href="http://sourceforge.net/project/memberlist.php?group_id=11">current
-              list of developers</a>.</p>
-            <p>
-              Sources can be checked out into a local working
-              directory according to <a
-              href="http://sourceforge.net/cvs/?group_id=11">these
-              instructions</a>.</p>
+            <p>Only developers can commit their changes to the
+            repository themselves.  Here is the <a
+            href="http://sourceforge.net/project/memberlist.php?group_id=11">current
+            list of developers</a>.</p>
+            <p>Sources can be checked out into a local working
+            directory according to <a
+            href="http://sourceforge.net/cvs/?group_id=11">these
+            instructions</a>.</p>
             <dl>
               <!-- one of (DD DT) -->
               <dt><strong>anonymously</strong></dt>
               </dd>
               <dt><strong>by developers via SSH</strong></dt>
               <dd>
-                <p>It allows developers to commit their changes
-                  (after getting approval for the patch sent to <a href="mailto:xemacs-patches@xemacs.org">xemacs-patches@xemacs.org</a>)
+                <p>It allows developers to commit their changes (after
+                  getting approval for the patch sent to <a href="mailto:xemacs-patches@xemacs.org">xemacs-patches@xemacs.org</a>)
                   to the repository directly.</p>
                 <p>This will cause the website to be updated and the
                   affected files validated automatically!</p>
             <p><a href="#index">Goto</a> Index</p>
             <p>This is performed via the shared project account named
               <strong>xemacs</strong>.  Its password can be found in
-              <samp>~xemacs/.ssh/secret</samp> after first logging as
+              <samp>~xemacs/.ssh/secret</samp> after first logging in as
               follows: <samp>ssh -l xemacs shell.sourceforge.net</samp>.
               You may never need this account, unless you get involved
               in improving the process or fixing breakage.</p>
             <p>Who could better validate XEmacs documentation than the
               master himself: XEmacs?</p>
             <p>A small lisp module, <a href="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/xemacsweb/batch-psgml-validate.el?cvsroot=xemacs">xemacsweb/batch-psgml-validate.el</a>,
-              utilizes <cite>PSGML</cite> to validate buffers, files,
-              or directories, according to the DTD they contain.</p>
+              utilizes <cite>PSGML</cite> to validate buffers, files, or
+              directories, according to the DTD they contain.</p>
             <hr>
             <h2><a name="Maclwg">Maintaining</a> a consistent look with genpage</h2>
             <p><a href="#index">Goto</a> Index</p>
-            <p>Whenever you think about changing <var>X</var>.html in this site,
-              please check whether <var>X</var>.content exists as well.  <strong>In
-                such a case, any changes you make to X.html will be
-                lost!</strong></p>
+            <p>Whenever you think about changing <var>X</var>.html in
+              this site, please check whether <var>X</var>.content
+              exists as well.  <strong>In such a case, any changes you
+                make to X.html will be lost!</strong></p>
+            <p>See <strong><a href="#GfC">Guidelines for
+                  Contributors</a></strong> for more information about
+              creating and editing .content files.</p>
             <p><a href="http://www.freddyfrog.com/hacks/genpage/">genpage</a>
               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 <a href="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/xemacsweb/template.html?cvsroot=xemacs">xemacsweb/template.html</a>.
               genpage is run by the <a href="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/xemacsweb/Makefile?cvsroot=xemacs">xemacsweb/Makefile</a>
-              according to the configuration defined in
-              <a href="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/xemacsweb/genpage.conf?cvsroot=xemacs">xemacsweb/genpage.conf</a>.</p>
+              according to the configuration defined in <a href="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/xemacsweb/genpage.conf?cvsroot=xemacs">xemacsweb/genpage.conf</a>.</p>
             <p>You may run this Makefile in your local xemacsweb
-              working directory, provided you have
-              <strong>perl5</strong> and <strong>GNU make</strong>
-              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.</p>
+            working directory, provided you have
+            <strong>XEmacs</strong> (including the
+            <strong>PSGML</strong> package), <strong>perl5</strong>
+            and <strong>GNU make</strong> 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.</p>
             <p>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
               for details).  These will need to be reviewed when a <a href="http://www.freddyfrog.com/hacks/genpage/completenews.html">newer
                 version</a> of genpage ever gets imported.</p>
             <hr>
-            <h2>Relative Links <a name="RLaMaOT">allow</a> Mirroring and Offsite Testing</h2>
+            <h2>Relative Links <a name="RLaMaOT">allow</a> Mirroring and Off-site Testing</h2>
             <p><a href="#index">Goto</a> Index</p>
             <p>Considerable work has been done to make all links
               <em>within</em> this website <em>relative</em>.  In
                 href="..."&gt;</strong> were eliminated since they add
               another twist.  Relative links become relative to the URL
               specified by <strong>&lt;base href="..."&gt;</strong>, not
-              relative to the document they apear in.</p>
+              relative to the document they appear in.</p>
             <p>Special consideration had to be given to <a href="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/xemacsweb/template.html?cvsroot=xemacs">xemacsweb/template.html</a>.
               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 <cite>relPath</cite>
+              been implemented by use of the <a href="../genpage/www/recipes/relPath.html">relPath</a>
               genpage recipe.</p>
             <hr>
             <h2><a name="GfC">Guidelines</a> for Contributors</h2>
             <p><a href="#index">Goto</a> Index</p>
-            <p>These rules serve the purpose of
-              <em>minimizing work</em> and <em>accelarating the learning
-                curve</em> for contributors.</p>
-            <p>The goal is to provide a high-quality,
-              consistent website, showing off the power of XEmacs and
-              its contributors.</p>
+            <p>These rules serve the purpose of <em>minimizing
+                work</em> and <em>accelerating the learning curve</em> for
+              contributors.</p>
+            <p>The goal is to provide a high-quality, consistent
+              website, showing off the power of XEmacs and its
+              contributors.</p>
             <p>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.</p>
+              contributors.  These just came in handy while I moved the
+              content over from www.xemacs.org -- Adrian.</p>
             <dl>
               <!-- one of (DD DT) -->
-              <dt>Use lower-case HTML tags</dt>
+              <dt><strong>Create .content files for new documentation</strong></dt>
               <dd>
-                <p>
-                  This is in preparation of a possible future
-                  migration to <cite>XML</cite>.</p></dd>
-              <dt>Use relative links wherever possible</dt>
+                <p>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
+                <strong>make all</strong> in the top-level directory
+                (xemacsweb).  This will generate a .html file by the
+                same name and validate it using XEmacs/PSGML.</p>
+                <p>Here is what a minimal .content file looks like:</p>
+                <table border="1">
+                  <tbody>
+                    <tr>
+                      <!-- one of (TD TH) -->
+                      <td>
+                        <pre>
+%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
+&lt;body&gt;...&lt;/body&gt; section of a corresponding HTML
+document.</pre>
+                      </td>
+                    </tr>
+                  </tbody>
+                </table>
+                <p></p>
+              </dd>
+              <dt><strong>Generate .content files from existing .html documents</strong></dt>
               <dd>
-                <p>
-                  This makes site mirroring a free gift and allows
-                  developers to test intra-site links in their private
-                  working directories off-site.</p></dd>
-              <dt>Edit .hmtl file and merge back to .content file</dt>
+                <p>Use <a href="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/xemacsweb/html2content.pl?cvsroot=xemacs">xemacsweb/html2content.pl</a>
+                  to convert all .html files in a specified directory
+                  (recursively) to .content files.  Existing .content
+                  files will not be overwritten.</p></dd>
+              <dt><strong>Edit .html file and merge back to .content file</strong></dt>
               <dd>
-                <p> This gives you the power of your favorite HMTL
+                <p>This gives you the power of your favorite HTML
                   editor (you are not using notepad, are you?) and
                   changes can easily be merged to the .content file with
                   <cite>ediff</cite>.</p></dd>
-              <dt>Use logical vs. physical markup</dt>
+              <dt><strong>Use lower-case HTML tags</strong></dt>
               <dd>
-                <p>It is a HTML authoring commandment to prefer
-                  logical markups like
-                  &lt;blockquote&gt;</p><blockquote>blockquote</blockquote>&lt;/blockquote&gt;,
+                <p>This is in preparation of a possible future
+                  migration to <cite>XML</cite>.</p></dd>
+              <dt><strong>Use relative links wherever possible</strong></dt>
+              <dd>
+                <p>This makes site mirroring a free gift and allows
+                  developers to test intra-site links in their private
+                  working directories off-site.</p></dd>
+              <dt><strong>Use logical vs. physical markup</strong></dt>
+              <dd>
+                <p>It is a HTML authoring commandment to prefer logical
+                  markups like &lt;blockquote&gt;</p>
+                <blockquote>
+                  blockquote</blockquote>&lt;/blockquote&gt;,
                 &lt;strong&gt;<strong>strong</strong>&lt;/strong&gt;,
                 &lt;cite&gt;<cite>cite</cite>&lt;/cite&gt;,
                 &lt;samp&gt;<samp>samp</samp>&lt;/samp&gt; over
                 &lt;br&gt;, &lt;b&gt;<b>bold</b>&lt;/b&gt;,
                 &lt;i&gt;<i>italic</i>&lt;/i&gt;, or
                 &lt;tt&gt;<tt>teletype</tt>&lt;/tt&gt;.
-                <p>Use &lt;pre&gt;</p><pre>Retrieving newsgroup: nnml:xemacs-beta...
+                <p>Use &lt;pre&gt;</p>
+                <pre>
+Retrieving newsgroup: nnml:xemacs-beta...
 Fetching headers for nnml:xemacs-beta...
 Fetching headers for nnml:xemacs-beta...done
 Suppressing duplicates...
 Generating summary...
 Generating summary...done
 Decoding base64...
-Decoding base64... done</pre>&lt;/pre&gt; for including 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
+Decoding base64... done</pre>
+                &lt;/pre&gt; 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
                 <pre>M-x <strong>html-quote-region</strong></pre>
               </dd>
-              <dt>Use qq{string}, not "string" in genpage commands</dt>
+              <dt><strong>Use qq{string}, not "string" in genpage commands</strong></dt>
               <dd>
                 <p>All genpage commands (as opposed to genpage content
                   tags) are embedded in HTML comments.  Whenever these
                   commands are embedded inside an HTML attribute,
                   embedded <cite>"</cite>s will produce an HTML
                   validation error.</p>
-                <p>
-                  Therefor, please use</p>
+                <p>Therefor, please use</p>
                 <pre>&lt;a href="&lt;!-- _GP_ relPath(<strong>qq{</strong>Develop/devTeam.html<strong>}</strong>) --&gt;"&gt;Who Wrote XEmacs?&lt;/a&gt;</pre>
                 <p>instead of</p>
                 <pre>&lt;a href="&lt;!-- _GP_ relPath("Develop/devTeam.html") --&gt;"&gt;Who Wrote XEmacs?&lt;/a&gt;</pre>
               <li>Automatic <a href="#AWU">Website</a> Update</li>
               <li>Automatic <a href="#AWV">Website</a> Validation</li>
               <li><a href="#Maclwg">Maintaining</a> a consistent look with genpage</li>
-              <li>Relative Links <a href="#RLaMaOT">allow</a> Mirroring and Offsite Testing</li>
+              <li>Relative Links <a href="#RLaMaOT">allow</a> Mirroring and Off-site Testing</li>
               <li><a href="#GfC">Guidelines</a> for Contributors</li>
             </ul>
             <hr>

File About/created.content

 	  <li><a href="http://www.ph.tum.de/~msprange/">Michael Spranger - personal homepage</a>
 	  <li><a href="http://www.katzbrown.com/">katzbrown.com</a>
 	  <li><a href="http://website.lineone.net/~ajhoughton/">Alastair's Place</a>
+	  <li><a href="http://dirac.ruc.dk/~gnalle/">Niels Langager Ellegaard</a>
 	</ul>
 	<br>
+2000-09-11  Adrian Aichner  <aichner@ecf.teradyne.com>
+
+	* Makefile: Add XEmacs mode specification: -*-Makefile-*-
+	* Makefile (htdocs): Add dependency gp to build documentation for
+	genpage itself.
+	* Makefile (gp): Add rule to build documentation for genpage
+	itself.
+	* Makefile (clean): Add clean target, prompted by Martin's
+	suggestion.
+	* batch-psgml-validate.el (batch-psgml-lazy-message): New.  Avoid
+	messages from `sgml-lazy-message' by encapsulation.
+	* html2content.pl: Modify script to be generally useful for
+	conversion from HTML to content files.
+
 2000-09-07  Yoshiki Hayashi  <yoshiki@xemacs.org>
 
 	* index.content: Point mailing lists to http://www.xemacs.org/.

File FAQ/ChangeLog

+2000-09-11  Adrian Aichner  <aichner@ecf.teradyne.com>
+
+	* xemacs-new.html: Change of "Last modified" time.
+
 2000-08-18  Adrian Aichner  <aichner@ecf.teradyne.com>
 
 	* index.content: Remove empty lines in genpage content tags to

File FAQ/xemacs-new.html

     
     <!-- Created: Wed Apr 16 11:20:47 MESZ 1997 -->
     <!-- hhmts start -->
-Last modified: Sun Aug 20 14:54:53 PDT 2000
+Last modified: Mon Sep 11 15:44:05 W. Europe Daylight Time 2000
 <!-- hhmts end -->
     <small>Conform with &lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
       "http://www.w3.org/TR/REC-html40/loose.dtd"&gt;
+# -*-Makefile-*- Begin of xemacsweb Makefile
 #
 # Adrian Aichner (APA), aichner@ecf.teradyne.com, Teradyne GmbH, 2000-07-29.
 #
 	$(XEMACS) $(FLAGS) -f batch-byte-compile $<
 
 # APA: Default target (first to occur in file):
-htdocs: $(ELCS) genpage-time-stamp
+htdocs: $(ELCS) gp genpage-time-stamp
 
 validate:  htdocs validate-time-stamp
 
+# APA: Build the genpage documentation
+gp:
+	cd genpage;	$(MAKE) gp
+
 all: validate
 
 # APA: When contentdir and outputdir are the same then, and only then,
 validate-time-stamp: $(HTML_FILES)
 	$(XEMACS) $(FLAGS) -l ./batch-psgml-validate.elc -f batch-psgml-validate $?
 	touch validate-time-stamp
+
+# APA: Remove all .html files (and backups) generated from .content
+# files.  Need to remove timestamp files as well!
+clean:
+	find . -name "*.content" -print | perl -ne "{ chomp; s/\.content/.html*/; unlink; }"
+	rm genpage-time-stamp
+	rm validate-time-stamp
+
+# End of xemacsweb Makefile

File batch-psgml-validate.el

     (throw sgml-throw-on-warning t)))
 (fset 'sgml-log-warning 'batch-psgml-validate-log-warning)
 
-;; APA: Encapsulate sgml-sgml-message to get rid of progress messages.
+;; APA: Encapsulate sgml-message to get rid of progress messages.
 (defun batch-psgml-validate-message (format &rest things)
 ;;; APA: Original body of sgml-message as of 2000-08-13:
 ;;;   (let ((buf (get-buffer sgml-log-buffer-name)))
 ;;;   (apply 'message format things)
   )
 (fset 'sgml-message 'batch-psgml-validate-message)
+
+;; APA: Encapsulate sgml-lazy-message to get rid of progress messages.
+(defun batch-psgml-lazy-message (&rest args)
+;;;   (unless (= sgml-lazy-time (second (current-time)))
+;;;     (apply 'message args)
+;;;     (setq sgml-lazy-time (second (current-time))))
+)
+(fset 'sgml-lazy-message 'batch-psgml-lazy-message)

File html2content.pl

 #! /usr/bin/perl -w
+# Author:
+# John S. Jacobs Anderson, jacobs@xemacs.org
+# Contributors:
+# Adrian Aichner (APA), aichner@ecf.teradyne.com, Teradyne GmbH, 2000-09-05.
 
+# APA: The "strict" pragma warns us about many potential user errors.
+use strict;
 use File::Find;
 
-find( \&changer , ( "content/Releases" ));
+if (scalar @ARGV) {
+  for (@ARGV) {
+    find( \&changer , ( "$_" ));
+  }
+} else {
+  die( "usage: html2content.pl DIR [DIR ...]
+
+Generate genpage .content files from .html files in DIR[s]\n" );
+}
 
 sub changer {
   my $file = $_;
-  if ( $file =~ '.html' ) {
+  if ( $file =~ '.html\Z' ) {
     my $contents;
     my $author;
     my $title;
       $contents = <IN>;
       close( IN );
     }
-    if ( $contents =~ m["author".*?content="(.*?)"]s ) { $author = $1;  }
-    else { die( "no author in $file!\n") }
-
-    if ( $contents =~ m[<title>(.*?)</title>] ) { $title = $1; }
-    else { die( "no title in $file!\n" ) }
-
-    if ( $contents =~ 
-	 m[<!-- content cell -->.*?<td align="left" valign="top">(.*)</td><!-- /content cell -->]s) {
+    if ( $contents =~ m["author".*?content="(.*?)"]s ) {
+      $author = $1;
+    } else {
+      $author = "unknown, please claim authorship!";
+      warn( "no author in $file!\n");
+    }
+    if ( $contents =~ m[<title>(.*?)</title>]si ) {
+      $title = $1;
+    } else {
+      die( "no title in $file!\n" );
+    }
+    if ( $contents =~
+         m[<!-- content cell -->.*?<td align="left" valign="top">(.*)</td><!-- /content cell -->]s) {
       $main = $1;
+    } elsif ($contents =~ m|<body[^>]*>(.*)</body>|si) {
+      $main = $1;
+    } else {
+      die( "no main in $file!\n" );
     }
-    else { die( "no main in $file!\n" ) }
-
-    open( OUT , ">$newfile" );
-    print OUT <<EOF;
+    if (-e "$newfile") {
+      warn( "\"$newfile\" in dir \"$File::Find::dir\" exists already, won't overwrite!\n" );
+    } else {
+      open( OUT , ">$newfile" );
+      print OUT <<EOF;
 %title%
 $title
-
 %author%
 $author
-
 %main%
 $main
 EOF
-
+    }
   }
 }