Annotation of htdocs/developers/htdocs.xml, revision 1.4

1.1       jschauma    1: <?xml version="1.0"?>
                      2: <!DOCTYPE webpage
                      3:   PUBLIC "-//Norman Walsh//DTD Website V2.2//EN"
                      4:     "http://docbook.sourceforge.net/release/website/2.2/website.dtd" [
                      5: 
                      6: <!ENTITY % man-refs.ent SYSTEM "../share/xml/man-refs.ent"> %man-refs.ent;
                      7: 
                      8: ]>
                      9: 
                     10: <webpage id="htdocs">
                     11: <config param="desc" value="Editing htdocs"/>
1.4     ! jschauma   12: <config param="cvstag" value="$NetBSD: htdocs.xml,v 1.3 2004/11/16 07:12:54 symka Exp $"/>
        !            13: <config param="rcsdate" value="$Date: 2004/11/16 07:12:54 $"/>
1.1       jschauma   14: <head>
                     15: <title>Editing htdocs</title>
                     16: </head>
                     17: 
                     18: <sect1 id="editing-htdocs">
                     19: 
                     20: <itemizedlist>
                     21:        <listitem>
                     22:                <ulink url="#general">General notes on htdocs</ulink>
                     23:                <itemizedlist>
                     24:                        <listitem><ulink url="#who-can-edit">Who can edit htdocs</ulink></listitem>
                     25:                        <listitem><ulink url="#what-is-required">What is required to edit htdocs</ulink></listitem>
                     26:                        <listitem><ulink url="#validate-html">Validate your HTML</ulink></listitem>
                     27:                        <listitem><ulink url="#netbsd-org">NetBSD.org naming scheme</ulink></listitem>
                     28:                        <listitem><ulink url="#dotlist-files">What are .list files?</ulink></listitem>
                     29:                        <listitem><ulink url="#convert-to-xml">Converting to XML</ulink></listitem>
                     30:                        <listitem><ulink url="#dotxml-files">Processing .xml (docbook-website) files</ulink></listitem>
                     31:                        <listitem><ulink url="#moving-files">Renaming or moving files</ulink></listitem>
                     32:                        <listitem><ulink url="#flaglinks">What is the reasoning behind the flag links with empty.gif?</ulink></listitem>
                     33:                        <listitem><ulink url="#webserver">How do the pages get to the web server, and when?</ulink></listitem>
                     34:                </itemizedlist>
                     35:        </listitem>
                     36:        <listitem>
                     37:                <ulink url="#specific">Adding to specific areas</ulink>
                     38:                <itemizedlist>
                     39:                        <listitem><ulink url="#adding-news-items">Adding News Items</ulink></listitem>
                     40:                        <listitem><ulink url="#adding-events">Adding Events</ulink></listitem>
                     41:                        <listitem><ulink url="#adding-mailinglists">Adding to/editing the MailingLists page</ulink></listitem>
                     42:                        <listitem><ulink url="#consultants">Consultants for hire</ulink></listitem>
                     43:                </itemizedlist>
                     44:        </listitem>
                     45:        <listitem>
                     46:                Related Documentation:
                     47:                <itemizedlist>
                     48:                        <listitem><ulink url="announce.html">News story guidelines</ulink></listitem>
                     49:                        <listitem><ulink url="translate.html">Translating htdocs</ulink></listitem>
                     50:                </itemizedlist>
                     51:        </listitem>
                     52: </itemizedlist>
                     53: 
                     54: <html:hr/>
                     55: 
                     56: <sect2 id="general">
                     57: <title>General notes on htdocs</title>
                     58: 
                     59: <sect3 id="who-can-edit">
                     60: <title>Who can edit htdocs</title>
                     61: <para>
                     62:     Anyone with write access to the NetBSD CVS tree can checkout
                     63:     htdocs and make changes, and in fact is encouraged to do so.
                     64:     In particular as developers add features and drivers they should
                     65:     update the appropriate hardware or port homepage. Use your
                     66:     NetBSD.org login against cvs.NetBSD.org and checkout 'htdocs'.
                     67: </para>
                     68: <para>
                     69:     Users without CVS commit access are encouraged to check out htdocs
                     70:     via anoncvs, and mail patches to www@NetBSD.org, see 
                     71:     <ulink url="#dotlist-files">below</ulink>.
                     72: </para>
                     73: </sect3>
                     74: 
                     75: <sect3 id="what-is-required">
                     76: <title>What is required to edit htdocs</title>
                     77: <para>
                     78:     <itemizedlist>
                     79:     <listitem>Read <ulink url="cvs-repos/cvs_intro.html">the CVS introduction</ulink>.</listitem>
                     80:     <listitem>Install <pkg>meta-pkgs/netbsd-www,</pkg> which provides the tools
                     81:        required to build the web site.</listitem>
                     82:     <listitem>Set your CVSROOT as indicated and run
                     83:        <para><programlisting>cvs checkout htdocs</programlisting></para></listitem>
                     84:     <listitem>Edit your preferred file, type <code><emphasis role="bold">make</emphasis></code> to rebuild
                     85:        the output files (if necessary).</listitem>
                     86:     <listitem>Check the results using <code><emphasis role="bold">cvs diff</emphasis></code>, and <code><emphasis role="bold">cvs
                     87:        commit</emphasis></code> if everything is good.</listitem>
                     88:     </itemizedlist>
                     89: </para>
                     90: </sect3>
                     91: 
                     92: <sect3 id="validate-html">
                     93: <title>Validate your HTML</title>
                     94: <para>
                     95:     After making any changes you should run your html through an HTML
                     96:     verifier such as <pkg>www/weblint,</pkg> or better still <ulink
                     97:     url="http://validator.w3.org/">http://validator.w3.org/</ulink>.
                     98:     The URL for a link to an index.html file should not include the
                     99:     trailing index.html.
                    100:     If you use weblint you may want to add the following to your
                    101:     <code>~/.weblintrc</code>.
                    102: </para>
                    103: <para>
                    104:     <programlisting>extension Netscape</programlisting>
                    105: </para>
                    106: </sect3>
                    107: 
1.3       symka     108: <sect3 id="NetBSD-org">
1.1       jschauma  109: <title>NetBSD.org naming scheme</title>
                    110: <para>
                    111:     Make sure you use NetBSD.org and not any other scheme (&#78;etbsd.org,
                    112:     &#110;etbsd.org, ...) in links, mailto's or other pointers. 
                    113: </para>
                    114: </sect3>
                    115: 
                    116: <sect3 id="dotlist-files">
                    117: <title>What are .list files?</title>
                    118: <para>
                    119:     <emphasis role="bold">The <code>.list</code> files are
                    120:     obsolete!</emphasis><html:br/>
                    121:     Please see <ulink url="#dotxml-files">this section</ulink> for details.
                    122:     The paragraphs below still apply to the currently existing <code>.list</code>
                    123:     files.
                    124: </para>
                    125: <para>
                    126:     A <code>.list</code> file contains standard HTML with additional special
                    127:     tags to simplify formatting. It used to be processed by <code><ulink
                    128:     url="../list2html.pl">list2html.pl</ulink></code> into the desired .html
1.2       jschauma  129:     file.  Since the <code>.list</code> files are now obsolete, they should not be
1.1       jschauma  130:     edited anymore.  If they need to be changed, they should be <ulink
                    131:     url="#convert-to-xml">converted to XML</ulink>.
                    132: </para>
                    133: <para>
                    134:     There should be a Makefile in each directory which handles processing
                    135:     the .list files into .html, and will recurse into any subdirs
                    136:     containing Makefiles.
                    137: </para>
                    138: <para>
                    139:     Continuation lines are understood (useful for the special tags).
                    140: </para>
                    141: <para>
                    142:     If you do not have CVS access and wish to submit changes, you
                    143:     can check out htdocs via anonymous CVS (see the <ulink
                    144:     url="cvs-repos/cvs_intro.html">NetBSD CVS HOWTO</ulink>). The best
                    145:     approach is usually to:
                    146:     <orderedlist>
                    147:        <listitem>Checkout the <emphasis>htdocs</emphasis> module
                    148:            <para><programlisting>cvs checkout htdocs</programlisting></para></listitem>
                    149:        <listitem>Edit the desired file. Most FAQ-style documents are
                    150:            generated from <code>.list</code> files, so it is best to check
                    151:            before editing.</listitem>
                    152:        <listitem>Run 'make' if you have edited .list or similar files.</listitem>
                    153:        <listitem><ulink url="#validate-html">Validate</ulink> the HTML. (Repeat
                    154:            these three steps as necessary).</listitem>
                    155:        <listitem>Submit a diff to &lt;<ulink url="mailto:www@NetBSD.org">www@NetBSD.org</ulink>&gt;
                    156:            using <emphasis role="bold">cvs diff</emphasis>, eg.
                    157:             <para><programlisting>cvs diff -u <emphasis>htdocs/path/to/file.list</emphasis></programlisting></para>
                    158:         </listitem>
                    159:     </orderedlist>
                    160: </para>
                    161: <para>
                    162:     You should run <emphasis role="bold">make</emphasis> before committing. You will need
                    163:     <pkg>lang/perl5</pkg> installed.
                    164: </para>
                    165: </sect3>
                    166: 
                    167: <sect3 id="convert-to-xml">
                    168: <title>Converting to XML</title>
                    169: <para>
                    170:     In order to facilitate global changes, we are currently converting the
                    171:     NetBSD website to XML (docbook-website).  As of 2004-11-15, any non-XML
                    172:     file that needs to be edited shall be converted to XML at the same time.
                    173:     You may find the script <code>htutils/scripts/list2xml</code> helpful to
                    174:     initiate the conversion of the old <code>.list</code> as well as plain
                    175:     <code>.html</code> files.
                    176: </para>
                    177: <para>
                    178:     After converting a file to XML, remember to add it to the
                    179:     <code>htdocs/layout.xml</code> file and regenerate the website.
                    180: </para>
                    181: </sect3>
                    182: 
                    183: <sect3 id="dotxml-files">
                    184: <title>Processing .xml (docbook-website) files</title>
                    185: <para>
                    186:     In order to build .html files from .xml files, you will need at
                    187:     least <pkg>textproc/libxslt</pkg> and <pkg>textproc/docbook-website</pkg>
                    188:     installed. These are installed as part of <pkg>meta-pkgs/netbsd-www</pkg>
                    189: </para>
                    190: <para>
                    191:     To regenerate, cd to htdocs/ and run
                    192:       <para><programlisting>make ./autolayout.xml</programlisting></para>
                    193:     Then run <code><emphasis role="bold">make</emphasis></code> in the target directory.
                    194: </para>
                    195: </sect3>
                    196: 
                    197: <sect3 id="moving-files">
                    198: <title>Renaming or moving files</title>
                    199: <para>
                    200: In order to move or rename files within htdocs, the following procedure is
                    201: recommended:
                    202: 
                    203: <itemizedlist>
                    204:  <listitem>copy the file from the original location to new location</listitem>
                    205:  <listitem>modify html of the original file:
                    206:    <itemizedlist>
                    207:      <listitem>include a
                    208:          <code>&lt;META HTTP-EQUIV=Refresh CONTENT="5; URL=new-location"&gt;</code>
                    209:          tag in the header</listitem>
                    210:      <listitem>remove all content except the header and the footer</listitem>
                    211:      <listitem>add a sentence saying that the page moved and hyperlink it to the new
                    212:          location</listitem>
                    213:    </itemizedlist></listitem>
                    214:   <listitem>cvs add the new file</listitem>
                    215:   <listitem>cvs commit the new file and the changes of the old file at the same
                    216:       time, so we have some cvs reference of when and why things moved</listitem>
                    217: </itemizedlist>
                    218: </para>
                    219: </sect3>
                    220: 
                    221: <sect3 id="flaglinks">
                    222: <title>What is the reasoning behind the flag links with empty.gif?</title>
                    223: <para>
                    224:     Each NetBSD 'flag' links at the base of each page has:
                    225:     <itemizedlist>
                    226:     <listitem>href containing netbsd-banner with no alt tag</listitem>
                    227:     <listitem>href containing empty gif with "NetBSD" alt tag and the
                    228:         words "Home Page"</listitem>
                    229:     </itemizedlist>
                    230:     This has the effect of:
                    231:     <itemizedlist>
                    232:     <listitem>Making the "NetBSD Home Page" link a single link in lynx,
                    233:        i.e. not a NetBSD link and a Home Page link.</listitem>
                    234:     <listitem>In netscape, causing the additional text to be centered and
                    235:         aligned "better" w.r.t the graphic.  Without it, at least
                    236:         in netscape, they show up at the bottom not centered
                    237:         vertically, and abut the graphic (or, if you include spaces,
                    238:         include nasty underlined blanks which looks broken).</listitem>
                    239:     </itemizedlist>
                    240:     It's a grotty hack, but it makes things look right.
                    241: </para>
                    242: </sect3>
                    243: 
                    244: <sect3 id="webserver">
                    245: <title>How do the pages get to the web server, and when?</title>
                    246: <para>
                    247:     The NetBSD webpages are stored in CVS in the "htdocs" repository.
                    248:     For security reasons, the htdocs repository is copied (via rsync)
                    249:     to www.NetBSD.org each hour, and the a local checkout is done from
                    250:     that copy of the repository. The checked out tree can be found in
                    251:     "<code>/NetBSD-www</code>". The repository is updated and checked out
                    252:     every hour, about 40 minutes after the full hour (*:40). If you
                    253:     make a commit to htdocs, it will take up to an hour before the
                    254:     changes show up.
                    255: </para>
                    256: <para>
                    257:     Note that there are several files like the Gnats database
                    258:     (<ulink url="http://www.NetBSD.org/Gnats/"/>), the pkgsrc and source changes
                    259:     in Changes/changes*.html and Changes/pkg-changes*.html, the RSS
                    260:     files in Changes/rss-*.xml etc. that are not part of htdocs but
                    261:     that get generated by various scripts out of cron jobs directly on
                    262:     the web server. Check out "htutils/changes/*" to get access to the
                    263:     scripts.
                    264: </para>
                    265: </sect3>
                    266: 
                    267: </sect2>
                    268: 
                    269: <sect2 id="specific">
                    270: <title>Adding to specific areas</title>
                    271: 
                    272: <sect3 id="adding-gallery-entries">
                    273: <title>Adding to the 'Sites running NetBSD' gallery</title>
                    274: <para>
                    275: If you have a <code>NETBSD GALLERY ADDITION</code> email from the <ulink
                    276: url="../gallery/addsite.html">htdocs/gallery/addsite.html</ulink> page:
                    277: <orderedlist>
                    278: <listitem>Ensure you have perl installed</listitem>
                    279: <listitem>Save the message in your copy/paste buffer </listitem>
                    280: <listitem><code>cd htdocs/gallery</code></listitem>
                    281: <listitem><code>./addsite.pl</code>, paste the buffer, add a ^D, and answer '<code>y</code>' if it parsed OK.</listitem>
                    282: <listitem><code>cvs commit</code></listitem>
                    283: </orderedlist>
                    284: Alternatively you can manually edit <code>htdocs/gallery/sites.data</code>, and
                    285: run <code>make</code>.
                    286: </para>
                    287: </sect3>
                    288: 
                    289: <sect3 id="adding-news-items">
                    290: <title>Adding News Items</title>
                    291: <para>
                    292: Most news items go into <ulink
1.4     ! jschauma  293: url="../Changes/">htdocs/Changes/index.xml</ulink> (see note on
        !           294: <ulink url="#dotxml-files">.xml files</ulink>).  Changes affecting a
1.1       jschauma  295: specific port should also be linked to from their htdocs/Port/*/ news section.
                    296: </para>
                    297: <para>
                    298: Important code news items should also be noted in the text
                    299: <currentsrc>doc/CHANGES</currentsrc>
                    300: file.
                    301: </para>
                    302: <para>Quick ``howto'' for the impatient (but please do read on for details):
                    303: <itemizedlist>
                    304: <listitem>cd htdocs/Changes</listitem>
                    305: <listitem>make update</listitem>
1.4     ! jschauma  306: <listitem>${EDITOR} index.xml</listitem>
1.1       jschauma  307: <listitem>make</listitem>
                    308: <listitem>make MSG="I added important NEWS!" commit</listitem>
                    309: </itemizedlist>
                    310: </para>
                    311: 
                    312: <sect4 id="before-anything">
                    313: <title>Before you do anything with htdocs:</title>
                    314: <orderedlist>
                    315: <listitem>Ensure you have perl installed for the <ulink url="#dotlist-files">.list
                    316:     files</ulink>.</listitem>
                    317: <listitem>Check out <code>htdocs</code> from the CVS repository.</listitem>
                    318: <listitem>If you already have a copy of htdocs in your tree, make sure you update it
                    319: regularly.  In particular, when adding news items, make sure that
                    320: gallery/events.* is up to date as well, as the events are pulled in from
                    321: there!</listitem>
                    322: </orderedlist>
                    323: </sect4>
                    324: 
                    325: <sect4 id="change-entry">
                    326: <title>To add a change entry:</title>
                    327: <orderedlist>
                    328: <listitem>Edit htdocs/Changes/index.list and search for the first line
                    329:     starting &lt;DATE&gt;.</listitem>
                    330: <listitem>Insert a new line of the form
                    331:     <para><programlisting>&lt;DATE&gt;<emphasis>tag</emphasis> <emphasis>date</emphasis> - <emphasis>title</emphasis></programlisting></para>
                    332:     where
                    333:     <itemizedlist>
                    334:     <listitem><emphasis>tag</emphasis> - A lowercase/number/hyphen identifier. eg: 'new-xx-driver'</listitem>
                    335:     <listitem><emphasis>date</emphasis> - In the form DAY MONTH YEAR. eg: '23 Jan 1999'</listitem>
                    336:     <listitem><emphasis>title</emphasis> - Freeform text for the entry title - can use \ to
                    337:        escape the end of line.</listitem>
                    338:     </itemizedlist>
                    339: </listitem>
                    340: <listitem>Add the body of the item. manual pages (eg: &man.ls.1;), and email
                    341:     addresses (eg: &lt;user@domain&gt;) will be automatically expanded. Feel
                    342:     free to use HTML tags, though this is not compulsory.</listitem>
                    343: <listitem>Run '<code>make</code>'</listitem>
                    344: </orderedlist>
                    345: </sect4>
                    346: 
                    347: <sect4 id="adding-links">
                    348: <title>Adding links from the main pages:</title>
                    349: <para>
                    350: By running <code>make</code> from within htdocs/Changes, you will automatically 
                    351: update <ulink url="../">htdocs/index.html</ulink> and the index pages of all supported
                    352: translations.  No further action on your part is required.
                    353: </para>
                    354: <para>
                    355: Alternatively, you can run <code>make index</code> from the htdocs toplevel
                    356: directory.
                    357: </para>
                    358: </sect4>
                    359: 
                    360: <sect4 id="link-specific">
                    361: <title>If you want to add a link from a port specific page:</title>
                    362: <orderedlist>
                    363: <listitem>Edit htdocs/Ports/<emphasis>arch</emphasis>/index.html, and search for the
                    364:     '&lt;!-- news --&gt;' block.</listitem>
                    365: <listitem>Add a new entry to the subsequent list in the form:
                    366: <para>
                    367: <programlisting>&lt;dt&gt;&lt;b&gt;<emphasis>date</emphasis>:&lt;/b&gt; <emphasis>title</emphasis>
                    368:     &lt;dd&gt;<emphasis>body of item</emphasis>
                    369:     &lt;p&gt;</programlisting>
                    370: </para>
                    371:     where
                    372:     <itemizedlist>
                    373:     <listitem><emphasis>date</emphasis> - Normally as YEAR.MONTH.DATE</listitem>
                    374:     <listitem><emphasis>title</emphasis> - Freeform (short) text title</listitem>
                    375:     <listitem><emphasis>body of item</emphasis> - Freeform text for the entry. Can span mutltiple
                    376:        lines and may use HTML tags and links.</listitem>
                    377:     </itemizedlist>
                    378: </listitem>
                    379: </orderedlist>
                    380: </sect4>
                    381: 
                    382: <sect4 id="finally">
                    383: <title>Finally:</title>
                    384: <orderedlist>
                    385: <listitem>You may want to <ulink url="#validate-html">validate the HTML</ulink> in
                    386:     your modified files.</listitem>
                    387: <listitem>Check in the files - do not forget any <code>.list</code> files will
                    388:     update the matching <code>.html</code>.  The command 'make commit', when
                    389:        issued from the htdocs toplevel directory, will commit the main
                    390:        index-page, Changes/index.* and all the translations index pages with
                    391:        a default message of "NEWS; regen".  If you would like to add a more
                    392:        specific message, use 'MSG="Added News regarding FooBar" make
                    393:        commit'.</listitem>
                    394: <listitem>If the news is noteworthy it is a good idea to submit it to some news
                    395:     sites, like 
                    396:     <ulink url="http://daily.daemonnews.org/add_story.php3">Daily Daemonnews</ulink>,
                    397:     <ulink url="http://www.osnews.com/submit.php">OSNews</ulink>,
                    398:     <ulink url="http://slashdot.org/submit.pl">Slashdot</ulink>,
                    399:     <ulink url="http://www.newsforge.com/submit.pl">Newsforge</ulink> and
                    400:     <ulink url="http://www.bsdforums.org/submitnews.php">BSDForums</ulink>.</listitem>
                    401: </orderedlist>
                    402: </sect4>
                    403: 
                    404: </sect3>
                    405: 
                    406: <sect3 id="adding-events">
                    407: <title>Adding Events</title>
                    408: <para>
                    409: The main index page also contains links to "Upcoming Events".  These links are
                    410: updated much like the <ulink url="#adding-news-items">News entries</ulink>:
                    411: </para>
                    412: <para>
                    413:   <programlisting>
                    414: cd .../htdocs/gallery
                    415: $EDITOR events.list
                    416: make events</programlisting>
                    417: </para>
                    418: 
                    419: <para>
                    420: Since the events are included on all the translations index pages, all these
                    421: pages need to be generated and committed as well.  This can be achieved by
                    422: issuing the 'make index' command from the htdocs directory.    
                    423: </para>
                    424: <para>
                    425:   <programlisting>
                    426: cd .../htdocs
                    427: make index
                    428: MSG="Added Event Foo" make commit</programlisting>
                    429: </para>
                    430: </sect3>
                    431: 
                    432: <sect3 id="adding-mailinglists">
                    433: <title>Adding to/editing the MailingLists page </title>
                    434: <para>
                    435: If a mailing-list is missing from the
                    436: <ulink url="../MailingLists/">MailingLists</ulink> page:
                    437: <orderedlist>
                    438: <listitem>Edit the htdocs/MailingLists/index.m4 file</listitem>
                    439: <listitem>Run the makefile in htdocs/MailingLists, it will generate the index.html</listitem>
                    440: <listitem>Confirm the generated html is good.</listitem>
                    441: <listitem>commit the index.m4 and index.html files.</listitem>
                    442: </orderedlist>
                    443: </para>
                    444: </sect3>
                    445: 
                    446: <sect3 id="consultants">
                    447: <title>Consultants for hire</title>
                    448: <para>
                    449: Before adding an entry to the ``Consultants for hire'' page (<ulink
                    450: url="../gallery/consultants.html">gallery/consultants.html</ulink>), please ask
                    451: that the person in question provides a link back to our homepage and/or
                    452: mentions NetBSD on their website.  Needless to say that you should make sure
                    453: that the URL given is active and accessible.
                    454: </para>
                    455: 
                    456: </sect3>
                    457: </sect2>
                    458: </sect1>
                    459: </webpage>

CVSweb <webmaster@jp.NetBSD.org>