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

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

CVSweb <webmaster@jp.NetBSD.org>