Annotation of htdocs/developers/htdocs.html, revision 1.166

1.158     jym         1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
1.122     kano        2: <html>
1.1       abs         3: <head>
1.82      jschauma    4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
1.115     heinz       5: <meta name="generator" content="Website XSL Stylesheet V2.6.0">
1.102     jschauma    6: <link rel="home" href="../." title="Welcome to The NetBSD Project: Of course it runs NetBSD.">
                      7: <link rel="up" href="../developers/." title="NetBSD Developer Documentation">
                      8: <link rel="previous" href="../developers/de-lint.html" title="How to de-lint files">
1.141     kano        9: <link rel="next" href="../developers/PR.html" title="Resolving Problem Reports">
1.115     heinz      10: <link rel="first" href="../developers/announce.html" title="NetBSD Developer Documentation: News story guidelines">
                     11: <link rel="last" href="../developers/www.html" title="NetBSD Developer Documentation: Information about the www
                     12:       mailing list">
1.144     dsieger    13: <link rel="stylesheet" href="../global.css" type="text/css">
1.1       abs        14: <title>Editing htdocs</title>
                     15: </head>
1.115     heinz      16: <body class="website"><div class="webpage">
1.133     dsieger    17: <a name="developers-htdocs"></a><div id="top"><a href="#mainContent" class="doNotDisplay doNotPrint">Skip to main content.</a></div>
1.158     jym        18: <div id="centralHeader">
1.160     jym        19: <div id="logo">
1.162     jym        20: <a href="../"><img alt="[NetBSD Logo]" src="../images/NetBSD-smaller.png"></a><div id="name"><a href="../">
1.160     jym        21:          The NetBSD Project
1.162     jym        22:        </a></div>
                     23: <div id="slogan"><a href="../">
1.160     jym        24:          &#8220;Of course it runs NetBSD&#8221;
1.162     jym        25:        </a></div>
1.160     jym        26: </div>
                     27: <div id="headerTools">
1.158     jym        28: <div id="header-cse-search-form">Google custom search</div>
1.152     spz        29: <script src="http://www.google.com/jsapi" type="text/javascript"></script><script type="text/javascript"> 
                     30:                  google.load('search', '1', {language : 'en'});
                     31:                  google.setOnLoadCallback(function() {
                     32:                    var header_customSearchControl = new google.search.CustomSearchControl('006277936787196004968:mbdhrauy1wm');
                     33:                    header_customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET);
                     34:                    var header_options = new google.search.DrawOptions();
                     35:                    header_options.enableSearchboxOnly("http://google.com/cse?cx=006277936787196004968:mbdhrauy1wm");    
                     36:                    header_customSearchControl.draw('header-cse-search-form', header_options);
                     37:                  }, true);
1.158     jym        38:                </script>
                     39: </div>
1.133     dsieger    40: </div>
1.158     jym        41: <div id="navBar" role="navigation">
1.136     dsieger    42: <span class="doNotDisplay">
                     43:          Navigation:
1.158     jym        44:        </span><ul>
                     45: <li><a href="../">
                     46:          Home</a></li>
                     47: <li>
                     48: <a href="../">
1.161     wiz        49:          News &amp; Media</a><ul>
1.158     jym        50: <li><a href="../changes/">
                     51:            Recent changes</a></li>
1.159     jym        52: <li><a href="http://blog.NetBSD.org/">
1.158     jym        53:            NetBSD blog</a></li>
                     54: <li><a href="../gallery/events.html">
                     55:            Events</a></li>
                     56: <li><a href="../changes/rss.html">
                     57:            Feeds</a></li>
                     58: </ul>
                     59: </li>
                     60: <li>
                     61: <a href="../about/">
                     62:          About</a><ul>
                     63: <li><a href="../about/">
                     64:            NetBSD</a></li>
                     65: <li><a href="../foundation/">
                     66:            The NetBSD Foundation</a></li>
                     67: <li><a href="../gallery/">
                     68:            Advocacy</a></li>
                     69: </ul>
                     70: </li>
                     71: <li>
                     72: <a href="../docs/">
                     73:          Documentation</a><ul>
                     74: <li><a href="../docs/misc/index.html">
                     75:            FAQ &amp; HOWTOs</a></li>
                     76: <li><a href="../docs/guide/en/">
                     77:            The Guide</a></li>
1.159     jym        78: <li><a href="http://man.NetBSD.org/">
1.158     jym        79:            Manual pages</a></li>
1.159     jym        80: <li><a href="http://wiki.NetBSD.org/">
1.158     jym        81:            Wiki</a></li>
                     82: </ul>
                     83: </li>
                     84: <li>
                     85: <a href="../support/">
                     86:          Support</a><ul>
                     87: <li><a href="../support/send-pr.html">
                     88:            Problem report guide</a></li>
                     89: <li><a href="../cgi-bin/sendpr.cgi?gndb=netbsd">
                     90:            Report a bug</a></li>
                     91: <li><a href="../support/query-pr.html">
                     92:            Query bug database</a></li>
                     93: <li><a href="../support/security/">
                     94:            Security</a></li>
                     95: </ul>
                     96: </li>
                     97: <li>
                     98: <a href="../community/">
                     99:          Community</a><ul>
                    100: <li><a href="http://onetbsd.org/">
                    101:            Blogs</a></li>
                    102: <li><a href="../mailinglists/">
                    103:            Mailing lists</a></li>
1.159     jym       104: <li><a href="http://mail-index.NetBSD.org/">
1.158     jym       105:            List archives</a></li>
                    106: </ul>
                    107: </li>
                    108: <li>
                    109: <a href="../developers/">
                    110:          Developers</a><ul>
1.159     jym       111: <li><a href="http://cvsweb.NetBSD.org/">
1.158     jym       112:            Browse source</a></li>
1.159     jym       113: <li><a href="http://nxr.NetBSD.org/">
1.158     jym       114:            Cross-reference</a></li>
1.159     jym       115: <li><a href="http://releng.NetBSD.org/">
1.158     jym       116:            Release engineering</a></li>
1.159     jym       117: <li><a href="http://wiki.NetBSD.org/projects/">
1.158     jym       118:            Projects list</a></li>
                    119: </ul>
                    120: </li>
                    121: <li>
                    122: <a href="../ports/">
                    123:          Ports</a><ul>
                    124: <li><a href="../ports/history.html">
                    125:            History</a></li>
                    126: <li><a href="../ports/emulators.html">
                    127:            Emulators</a></li>
                    128: </ul>
                    129: </li>
                    130: <li>
                    131: <a href="http://www.pkgsrc.org/">
                    132:          Packages</a><ul>
                    133: <li><a href="http://www.pkgsrc.se/">
                    134:            Browse packages</a></li>
1.159     jym       135: <li><a href="http://releng.NetBSD.org/index-pkgsrc.html">
1.158     jym       136:            Release engineering</a></li>
                    137: </ul>
                    138: </li>
                    139: </ul>
1.133     dsieger   140: </div>
                    141: <div id="content"><div class="fullWidth"><div class="rowOfBoxes">
                    142: <h1>Editing htdocs</h1>
1.108     wiz       143: <h3 class="title"><a name="general">General notes on htdocs</a></h3>
1.94      jschauma  144: <ul>
                    145: <li><a href="#who-can-edit">Who can edit htdocs</a></li>
                    146: <li><a href="#what-is-required">What is required to edit htdocs</a></li>
                    147: <li><a href="#validate-html">Validate your HTML</a></li>
                    148: <li><a href="#NetBSD-org">NetBSD.org naming scheme</a></li>
                    149: <li><a href="#dotlist-files">What are .list files?</a></li>
                    150: <li><a href="#convert-to-xml">Converting to XML</a></li>
                    151: <li><a href="#dotxml-files">Processing .xml (docbook-website) files</a></li>
                    152: <li><a href="#moving-files">Renaming or moving files</a></li>
                    153: <li><a href="#flaglinks">What is the reasoning behind the flag links with empty.gif?</a></li>
1.125     jschauma  154: <li><a href="#templates">XML template files</a></li>
1.94      jschauma  155: <li><a href="#webserver">How do the pages get to the web server, and when?</a></li>
                    156: </ul>
1.121     rillig    157: <h3 class="title"><a name="structure">How is the whole web site structured?</a></h3>
                    158: <ul>
                    159: <li><a href="#structure-overview">Overview</a></li>
                    160: <li><a href="#structure-directories">What are the individual directories for?</a></li>
                    161: <li><a href="#structure-files">What are the individual files for?</a></li>
                    162: </ul>
1.108     wiz       163: <h3 class="title"><a name="specific">Adding to specific areas</a></h3>
1.94      jschauma  164: <ul>
1.118     daniel    165: <li><a href="#adding-gallery-entries">Adding to the Sites running NetBSD gallery</a></li>
                    166: <li><a href="#adding-gallery-screenshots">Adding to the NetBSD in action gallery</a></li>
1.94      jschauma  167: <li><a href="#adding-news-items">Adding News Items</a></li>
                    168: <li><a href="#adding-events">Adding Events</a></li>
                    169: <li><a href="#adding-mailinglists">Adding to/editing the MailingLists page </a></li>
                    170: <li><a href="#consultants">Consultants for hire</a></li>
                    171: </ul>
                    172: <hr>
                    173: <h3 class="title">General notes on htdocs</h3>
                    174: <h4 class="title">
                    175: <a name="who-can-edit"></a>Who can edit htdocs (<a href="#general">top</a>)
                    176:   </h4>
1.82      jschauma  177: <p>
1.16      abs       178:     Anyone with write access to the NetBSD CVS tree can checkout
                    179:     htdocs and make changes, and in fact is encouraged to do so.
                    180:     In particular as developers add features and drivers they should
                    181:     update the appropriate hardware or port homepage. Use your
1.70      keihan    182:     NetBSD.org login against cvs.NetBSD.org and checkout 'htdocs'.
1.82      jschauma  183: </p>
                    184: <p>
1.79      hubertf   185:     Users without CVS commit access are encouraged to check out htdocs
1.155     wiz       186:     via anoncvs, and mail patches to www@NetBSD.org; see
1.144     dsieger   187:     <a class="ulink" href="#dotlist-files" target="_top">below</a>.
1.82      jschauma  188: </p>
                    189: 
1.94      jschauma  190: <h4 class="title">
                    191: <a name="what-is-required"></a>What is required to edit htdocs (<a href="#general">top</a>)
                    192:   </h4>
1.82      jschauma  193: <p>
1.99      jschauma  194:   </p>
1.164     tron      195: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.152     spz       196: <li class="listitem">Read <a class="ulink" href="cvs-repos/cvs_intro.html" target="_top">the CVS
1.99      jschauma  197:       introduction</a>.
                    198:     </li>
1.155     wiz       199: <li class="listitem">Install <a href="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/netbsd-www/README.html" target="_top"><code class="filename">meta-pkgs/netbsd-www</code></a>,
1.116     rpaulo    200:         which provides the tools
1.100     jschauma  201:        required to build the web site.  Please make sure that you have at
1.155     wiz       202:        least <a href="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/textproc/docbook-xsl/README.html" target="_top"><code class="filename">textproc/docbook-xsl</code></a>
1.116     rpaulo    203:        &gt;= 1.68.1 and
1.155     wiz       204:        <a href="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/textproc/docbook-website/README.html" target="_top"><code class="filename">textproc/docbook-website</code></a>
1.117     mishka    205:        &gt;= 2.6.0nb1 (automatically
1.154     tron      206:        required by <a href="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/netbsd-www/README.html" target="_top"><code class="filename">meta-pkgs/netbsd-www</code></a>
1.117     mishka    207:        1.4, but earlier versions accepted earlier revisions of
1.155     wiz       208:        required tools, which may not be appropriate).  Please note that
1.120     jlam      209:        any special LOCALBASE or PKG_SYSCONFBASE settings in
                    210:        <code class="filename">/etc/mk.conf</code> should <span class="emphasis"><em>not</em></span>
                    211:        be protected by BSD_PKG_MK as their values are used by the htdocs
                    212:        makefiles.
1.99      jschauma  213:     </li>
1.152     spz       214: <li class="listitem">Also install
1.154     tron      215:        <a href="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/netbsd-doc-print/README.html" target="_top"><code class="filename">meta-pkgs/netbsd-doc-print</code></a>
1.145     tsutsui   216:        to regenerate <a class="ulink" href="../docs/guide/en/" target="_top">The NetBSD guide</a>
                    217:        and some other pages which depend on the guide.
                    218:     </li>
1.152     spz       219: <li class="listitem">Set your CVSROOT as indicated and run
1.129     kano      220:       <pre class="programlisting">cvs checkout htdocs</pre>
1.99      jschauma  221:     </li>
1.152     spz       222: <li class="listitem">Edit your preferred file, type
1.99      jschauma  223:       <code class="code"><span class="bold"><strong>make</strong></span></code>
                    224:       to rebuild the output files (if necessary).
                    225:     </li>
1.152     spz       226: <li class="listitem">Check the results using
1.99      jschauma  227:       <code class="code"><span class="bold"><strong>cvs diff</strong></span></code>, and
                    228:       <code class="code"><span class="bold"><strong>cvs commit</strong></span></code> if everything
                    229:       is good.
                    230:     </li>
1.82      jschauma  231: </ul></div>
                    232: <p>
                    233: </p>
                    234: 
1.94      jschauma  235: <h4 class="title">
                    236: <a name="validate-html"></a>Validate your HTML (<a href="#general">top</a>)
                    237:   </h4>
1.82      jschauma  238: <p>
1.25      abs       239:     After making any changes you should run your html through an HTML
1.155     wiz       240:     verifier such as <a href="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/weblint/README.html" target="_top"><code class="filename">www/weblint</code></a>,
1.144     dsieger   241:     or better still <a class="ulink" href="http://validator.w3.org/" target="_top">http://validator.w3.org/</a>.
1.25      abs       242:     The URL for a link to an index.html file should not include the
                    243:     trailing index.html.
                    244:     If you use weblint you may want to add the following to your
1.91      wiz       245:     <code class="code">~/.weblintrc</code>.
1.82      jschauma  246: </p>
                    247: <p>
                    248:     </p>
1.129     kano      249: <pre class="programlisting">extension Netscape</pre>
1.82      jschauma  250: <p>
                    251: </p>
1.1       abs       252: 
1.94      jschauma  253: <h4 class="title">
                    254: <a name="NetBSD-org"></a>NetBSD.org naming scheme (<a href="#general">top</a>)
                    255:   </h4>
1.82      jschauma  256: <p>
                    257:     Make sure you use NetBSD.org and not any other scheme (Netbsd.org,
1.155     wiz       258:     netbsd.org, ...) in links, mailto's, or other pointers.
1.82      jschauma  259: </p>
                    260: 
1.94      jschauma  261: <h4 class="title">
                    262: <a name="dotlist-files"></a>What are .list files? (<a href="#general">top</a>)
                    263:   </h4>
1.82      jschauma  264: <p>
1.91      wiz       265:     <span class="bold"><strong>The <code class="code">.list</code> files are
1.124     mishka    266:     obsolete!</strong></span><br>
1.106     jschauma  267:     You should convert any existing <code class="code">.list</code> files to XML.
1.144     dsieger   268:     Please see <a class="ulink" href="#convert-to-xml" target="_top">this section</a> for details.
1.82      jschauma  269: </p>
1.41      dent      270: 
1.94      jschauma  271: <h4 class="title">
                    272: <a name="convert-to-xml"></a>Converting to XML (<a href="#general">top</a>)
                    273:   </h4>
1.82      jschauma  274: <p>
                    275:     In order to facilitate global changes, we are currently converting the
                    276:     NetBSD website to XML (docbook-website).  As of 2004-11-15, any non-XML
                    277:     file that needs to be edited shall be converted to XML at the same time.
1.130     daniel    278:     You may find the script <code class="code">htdocs/scripts/list2xml</code> helpful to
1.91      wiz       279:     initiate the conversion of the old <code class="code">.list</code> as well as plain
                    280:     <code class="code">.html</code> files.  Please note, however, that this script only
1.90      jschauma  281:     does a few simple replacements of tags, and you will need to do a lot by
                    282:     hand after running it.  In particular, you need to make sure that all
                    283:     tags are closed in the proper order.
                    284: </p>
                    285: <p>
1.91      wiz       286:     When creating or converting <code class="code">.xml</code> files, please make sure to
1.152     spz       287:     add a <span class="quote">&#8220;<span class="quote">id</span>&#8221;</span> attribute to each <code class="code">&lt;sect[1-4]&gt;</code>
1.93      jschauma  288:     as well as each <code class="code">&lt;table&gt;</code> tag:  this will prevent
1.144     dsieger   289:     <span class="command"><strong>xsltproc</strong></span> to generate an ID
1.91      wiz       290:     itself, which would require an update of the resulting <code class="code">.html</code>
1.116     rpaulo    291:     file after each regeneration. Also remember to replace each
1.152     spz       292:     <span class="quote">&#8220;<span class="quote">&amp;</span>&#8221;</span> with <span class="quote">&#8220;<span class="quote">&amp;amp;</span>&#8221;</span> and
1.116     rpaulo    293:     <code class="filename">/sys</code> with <code class="filename">/usr/src/sys</code>
                    294:     where applicable.
1.90      jschauma  295: </p>
                    296: <p>
                    297:     If you are unsure how to convert a given HTML tag to the XML equivalent,
                    298:     you may find some useful examples installed as part of the
1.154     tron      299:     <a href="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/textproc/docbook-website/README.html" target="_top"><code class="filename">textproc/docbook-website</code></a> on your system.
1.116     rpaulo    300:     And of course you can
1.90      jschauma  301:     feel free to ask on the www@ list for help.
1.82      jschauma  302: </p>
                    303: <p>
1.94      jschauma  304:     If you want an autogenerated TOC, you will need to include the following
                    305:     code:
1.93      jschauma  306:     </p>
1.129     kano      307: <pre class="programlisting">&lt;sect1 role="toc"&gt;</pre>
1.93      jschauma  308: <p>
1.94      jschauma  309:     This will generate a TOC listing all <code class="code">&lt;sect2&gt;</code>s with a
                    310:     bulleted list of its <code class="code">&lt;sect3&gt;</code>s.
1.93      jschauma  311: </p>
                    312: <p>
1.82      jschauma  313:     After converting a file to XML, remember to add it to the
1.91      wiz       314:     <code class="code">htdocs/layout.xml</code> file and regenerate the website.  See
1.144     dsieger   315:     <a class="ulink" href="#dotxml-files" target="_top">below</a> for details.
1.82      jschauma  316: </p>
1.37      dent      317: 
1.106     jschauma  318: 
1.94      jschauma  319: <h4 class="title">
                    320: <a name="dotxml-files"></a>Processing .xml (docbook-website) files (<a href="#general">top</a>)
                    321:   </h4>
1.82      jschauma  322: <p>
1.76      grant     323:     In order to build .html files from .xml files, you will need at
1.155     wiz       324:     least <a href="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/textproc/libxslt/README.html" target="_top"><code class="filename">textproc/libxslt</code></a> and
1.154     tron      325:     <a href="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/textproc/docbook-website/README.html" target="_top"><code class="filename">textproc/docbook-website</code></a>
                    326:     installed. These are installed as part of <a href="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/netbsd-www/README.html" target="_top"><code class="filename">meta-pkgs/netbsd-www</code></a>.
                    327:     Please make sure that you have <a href="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/netbsd-www/README.html" target="_top"><code class="filename">meta-pkgs/netbsd-www</code></a> version
1.117     mishka    328:     1.4.
1.82      jschauma  329: </p>
                    330: <p>
1.107     jschauma  331:     To regenerate, just run
1.114     darcy     332:     <code class="code"><span class="bold"><strong>make</strong></span></code> in the target directory.
1.99      jschauma  333: </p>
                    334: <p>
1.107     jschauma  335:     If you added a new file to <code class="filename">layout.xml</code>,
1.156     darcy     336:     then you do need to run <code class="code">make</code> in the htdocs top level.
1.82      jschauma  337: </p>
1.66      jschauma  338: 
1.94      jschauma  339: <h4 class="title">
                    340: <a name="moving-files"></a>Renaming or moving files (<a href="#general">top</a>)
                    341:   </h4>
1.82      jschauma  342: <p>
1.66      jschauma  343: In order to move or rename files within htdocs, the following procedure is
                    344: recommended:
                    345: 
1.82      jschauma  346: </p>
1.164     tron      347: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.152     spz       348: <li class="listitem">copy the file from the original location to new location</li>
                    349: <li class="listitem">cvs add the new file and cvs rm the old file</li>
                    350: <li class="listitem">add a note to <code class="filename">htdocs/errors/index.xml</code>, linking
1.99      jschauma  351:       to the new location
                    352:   </li>
1.152     spz       353: <li class="listitem">cvs commit the new file and the old file at the same
1.99      jschauma  354:       time, so we have some cvs reference of when and why
                    355:       things moved.
                    356:   </li>
1.82      jschauma  357: </ul></div>
                    358: <p>
                    359: </p>
1.66      jschauma  360: 
1.94      jschauma  361: <h4 class="title">
                    362: <a name="flaglinks"></a>What is the reasoning behind the flag links with empty.gif? (<a href="#general">top</a>)
                    363:   </h4>
1.82      jschauma  364: <p>
1.21      abs       365:     Each NetBSD 'flag' links at the base of each page has:
1.82      jschauma  366:     </p>
1.164     tron      367: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.152     spz       368: <li class="listitem">href containing netbsd-banner with no alt tag</li>
                    369: <li class="listitem">href containing empty gif with "NetBSD" alt tag and the
1.82      jschauma  370:         words "Home Page"</li>
                    371: </ul></div>
                    372: <p>
1.21      abs       373:     This has the effect of:
1.82      jschauma  374:     </p>
1.164     tron      375: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.152     spz       376: <li class="listitem">Making the "NetBSD Home Page" link a single link in lynx,
1.82      jschauma  377:        i.e. not a NetBSD link and a Home Page link.</li>
1.152     spz       378: <li class="listitem">In netscape, causing the additional text to be centered and
1.21      abs       379:         aligned "better" w.r.t the graphic.  Without it, at least
                    380:         in netscape, they show up at the bottom not centered
1.65      jschauma  381:         vertically, and abut the graphic (or, if you include spaces,
1.82      jschauma  382:         include nasty underlined blanks which looks broken).</li>
                    383: </ul></div>
                    384: <p>
1.21      abs       385:     It's a grotty hack, but it makes things look right.
1.82      jschauma  386: </p>
                    387: 
1.125     jschauma  388:     <h4 class="title">
                    389: <a name="templates"></a>XML template files (<a href="#general">top</a>)
                    390:   </h4>
                    391: 
                    392:     <p>
                    393:       There are a few template files in <code class="filename">htutils/templates</code>
                    394:       to get you started with XML.  Please compare to existing pages in use
                    395:       when you add new content.
                    396:     </p>
                    397:   
1.94      jschauma  398: <h4 class="title">
                    399: <a name="webserver"></a>How do the pages get to the web server, and when? (<a href="#general">top</a>)
                    400:   </h4>
1.82      jschauma  401: <p>
1.47      hubertf   402:     The NetBSD webpages are stored in CVS in the "htdocs" repository.
1.166   ! spz       403:     mollari updates the website from CVS in the live website under
        !           404:     <span class="quote">&#8220;<span class="quote"><code class="code">/u0/www</code></span>&#8221;</span>. --&gt;The script performing this
1.106     jschauma  405:     functionality is <code class="filename">htutils/scripts/update.http</code> and it
                    406:     is run about 40 minutes after the full hour (*:40). If you
1.47      hubertf   407:     make a commit to htdocs, it will take up to an hour before the
                    408:     changes show up.
1.82      jschauma  409: </p>
                    410: <p>
1.47      hubertf   411:     Note that there are several files like the Gnats database
1.144     dsieger   412:     (<a class="ulink" href="http://www.NetBSD.org/Gnats/" target="_top">http://www.NetBSD.org/Gnats/</a>), the pkgsrc and source changes
1.139     kano      413:     in changes/changes*.html and changes/pkg-changes*.html, the RSS
                    414:     files in changes/rss-*.xml etc. that are not part of htdocs but
1.47      hubertf   415:     that get generated by various scripts out of cron jobs directly on
                    416:     the web server. Check out "htutils/changes/*" to get access to the
                    417:     scripts.
1.82      jschauma  418: </p>
1.94      jschauma  419: <hr>
1.121     rillig    420: <h3 class="title">How is the whole web site structured?</h3>
                    421: <h4 class="title">
                    422: <a name="structure-overview"></a>Overview (<a href="#structure">top</a>)
                    423:   </h4>
                    424: 
                    425:        <p></p>
                    426: 
                    427: 
                    428: <h4 class="title">
                    429: <a name="structure-directories"></a>What are the individual directories for? (<a href="#structure">top</a>)
                    430:   </h4>
                    431: 
1.164     tron      432:        <div class="variablelist"><dl class="variablelist">
1.122     kano      433: <dt><span class="term"><code class="filename">share/mk</code></span></dt>
1.163     riz       434: <dd><p>Contains the <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-6.0+i386">make(1)</a> infrastructure to
1.121     rillig    435:        automatize the generation of the web pages from the source
                    436:        files.</p></dd>
1.122     kano      437: <dt><span class="term"><code class="filename">share/xml</code></span></dt>
1.121     rillig    438: <dd><p>[TODO]</p></dd>
1.122     kano      439: <dt><span class="term"><code class="filename">share/xsl</code></span></dt>
1.121     rillig    440: <dd><p>[TODO]</p></dd>
1.122     kano      441: <dt><span class="term"><code class="filename"></code></span></dt>
1.121     rillig    442: <dd><p></p></dd>
1.122     kano      443: <dt><span class="term"><code class="filename"></code></span></dt>
1.121     rillig    444: <dd><p></p></dd>
1.122     kano      445: <dt><span class="term"><code class="filename"></code></span></dt>
1.121     rillig    446: <dd><p></p></dd>
1.122     kano      447: <dt><span class="term"><code class="filename"></code></span></dt>
1.121     rillig    448: <dd><p></p></dd>
1.122     kano      449: <dt><span class="term"><code class="filename"></code></span></dt>
1.121     rillig    450: <dd><p></p></dd>
1.122     kano      451: <dt><span class="term"><code class="filename"></code></span></dt>
1.121     rillig    452: <dd><p></p></dd>
1.122     kano      453: <dt><span class="term"><code class="filename"></code></span></dt>
1.121     rillig    454: <dd><p></p></dd>
                    455: </dl></div>
                    456: 
                    457: 
                    458: <h4 class="title">
                    459: <a name="structure-files"></a>What are the individual files for? (<a href="#structure">top</a>)
                    460:   </h4>
                    461: 
1.164     tron      462:        <div class="variablelist"><dl class="variablelist">
1.122     kano      463: <dt><span class="term"><code class="filename">Makefile</code></span></dt>
1.121     rillig    464: <dd><p>Contains a description of the directory's
                    465:        contents. Usually it suffers to define the variables
                    466:        <code class="varname">SUBDIR</code> and <code class="varname">XMLDOCS</code>, and
1.144     dsieger   467:        then <span class="command"><strong>.include</strong></span> the file
1.121     rillig    468:        <code class="filename">htdocs/share/mk/web.site.mk</code> using the
1.128     rillig    469:        appropriate relative path. The files in the
                    470:        <code class="filename">share/mk</code> contain large comments at the top
                    471:        that describe what you can do in the
                    472:        <code class="filename">Makefile</code>.</p></dd>
1.122     kano      473: <dt><span class="term"><code class="filename">*.xml</code></span></dt>
1.129     kano      474: <dd><p>XML files contain the source code for a single
1.152     spz       475:        HTML page, in the <span class="quote">&#8220;<span class="quote">DocBook Website</span>&#8221;</span>
1.121     rillig    476:        format.</p></dd>
1.122     kano      477: <dt><span class="term"><code class="filename">layout.xml</code></span></dt>
1.121     rillig    478: <dd><p>[TODO]</p></dd>
1.122     kano      479: <dt><span class="term"><code class="filename">autolayout.xml</code></span></dt>
1.121     rillig    480: <dd><p>[TODO]</p></dd>
                    481: </dl></div>
                    482: 
                    483: <hr>
1.94      jschauma  484: <h3 class="title">Adding to specific areas</h3>
                    485: <h4 class="title">
1.152     spz       486: <a name="adding-gallery-entries"></a>Adding to the <span class="quote">&#8220;<span class="quote">Sites running NetBSD</span>&#8221;</span> gallery (<a href="#specific">top</a>)
1.94      jschauma  487:   </h4>
1.82      jschauma  488: <p>
1.144     dsieger   489: If you have a <code class="code">NETBSD GALLERY ADDITION</code> email from the <a class="ulink" href="../gallery/addsite.html" target="_top">htdocs/gallery/addsite.html</a> page:
1.82      jschauma  490: </p>
1.152     spz       491: <div class="orderedlist"><ol class="orderedlist" type="1">
                    492: <li class="listitem">Verify that the remote site has a link back to www.NetBSD.org.
1.99      jschauma  493:     If they do not link back, contact them to ask for a link back and add
                    494:     the information once the link is provided.</li>
1.156     darcy     495: <li class="listitem">Ensure you have perl installed.</li>
                    496: <li class="listitem">Save the message in your copy/paste buffer.</li>
                    497: <li class="listitem">
                    498: <code class="code">cd htdocs/gallery</code>.</li>
1.152     spz       499: <li class="listitem">
1.99      jschauma  500: <code class="code">./addsite.pl</code>, paste the buffer, add a ^D, and answer
1.156     darcy     501:       <code class="code">y</code> if it parsed OK.</li>
                    502: <li class="listitem">
                    503: <code class="code">cvs commit</code>.</li>
1.82      jschauma  504: </ol></div>
                    505: <p>
1.91      wiz       506: Alternatively you can manually edit <code class="code">htdocs/gallery/sites.data</code>, and
                    507: run <code class="code">make</code>.
1.82      jschauma  508: </p>
                    509: 
1.94      jschauma  510: <h4 class="title">
1.152     spz       511: <a name="adding-gallery-screenshots"></a>Adding to the <span class="quote">&#8220;<span class="quote">NetBSD in action</span>&#8221;</span> gallery (<a href="#specific">top</a>)
1.118     daniel    512:   </h4>
                    513: <p>
                    514: If possible, a screenshot should contain some easily recognizable visual
1.120     jlam      515: indication that it was made on a NetBSD system. A common way to do this is
1.156     darcy     516: by showing an X terminal that displays the output of <code class="code">uname -a</code>.
1.118     daniel    517: </p>
                    518: 
                    519: <h4 class="title">
1.94      jschauma  520: <a name="adding-news-items"></a>Adding News Items (<a href="#specific">top</a>)
                    521:   </h4>
1.82      jschauma  522: <p>
1.144     dsieger   523: Most news items go into <a class="ulink" href="../changes/" target="_top">htdocs/changes/index.xml</a> (see note on
                    524: <a class="ulink" href="#dotxml-files" target="_top">.xml files</a>).  Changes affecting a
1.143     kano      525: specific port should also be linked to from their htdocs/ports/*/ news section.
1.82      jschauma  526: </p>
1.6       abs       527: <p>
                    528: Important code news items should also be noted in the text
1.93      jschauma  529: <a href="http://cvsweb.NetBSD.org/bsdweb.cgi/src/doc/CHANGES?rev=HEAD&amp;content-type=text/x-cvsweb-markup">src/doc/CHANGES</a>
1.17      abs       530: file.
1.82      jschauma  531: </p>
1.69      jschauma  532: <p>Quick ``howto'' for the impatient (but please do read on for details):
1.82      jschauma  533: </p>
1.164     tron      534: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.152     spz       535: <li class="listitem">cd htdocs/changes</li>
                    536: <li class="listitem">make update</li>
                    537: <li class="listitem">${EDITOR} index.xml</li>
                    538: <li class="listitem">make</li>
                    539: <li class="listitem">make MSG="I added important NEWS!" commit</li>
1.82      jschauma  540: </ul></div>
                    541: <p>
                    542: </p>
                    543: 
1.164     tron      544: <div class="sect4">
1.91      wiz       545: <div class="titlepage"><div><div><h5 class="title">
                    546: <a name="before-anything"></a>Before you do anything with htdocs:</h5></div></div></div>
1.6       abs       547: 
1.152     spz       548: <div class="orderedlist"><ol class="orderedlist" type="1">
1.154     tron      549: <li class="listitem">Ensure you have <a href="http://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/netbsd-www/README.html" target="_top"><code class="filename">meta-pkgs/netbsd-www</code></a> installed.
1.144     dsieger   550:     Also, see <a class="ulink" href="#what-is-required" target="_top">above</a>.</li>
1.152     spz       551: <li class="listitem">Check out <code class="code">htdocs</code> from the CVS repository.</li>
                    552: <li class="listitem">If you already have a copy of htdocs in your tree, make sure you
1.99      jschauma  553:     update it regularly.  In particular, when adding news items, make sure that
                    554:     gallery/events.* is up to date as well, as the events are pulled in from
                    555:     there!  This is best done by running
1.129     kano      556:     <pre class="programlisting">
1.90      jschauma  557:   $ cd htdocs
1.129     kano      558:   $ make update</pre>
1.99      jschauma  559:   </li>
1.82      jschauma  560: </ol></div>
                    561: </div>
                    562: 
1.164     tron      563: <div class="sect4">
1.91      wiz       564: <div class="titlepage"><div><div><h5 class="title">
                    565: <a name="change-entry"></a>To add a change entry:</h5></div></div></div>
1.6       abs       566: 
1.152     spz       567: <div class="orderedlist"><ol class="orderedlist" type="1">
1.156     darcy     568: <li class="listitem">Edit htdocs/changes/index.xml.</li>
1.152     spz       569: <li class="listitem">In the right section, add the entry of the form
1.129     kano      570:     <pre class="programlisting">
1.90      jschauma  571:   &lt;sect3 id="link-name&gt;
1.94      jschauma  572:   &lt;title&gt;XX Mon XXX - FREEFORM TITLE&lt;/title&gt;
1.90      jschauma  573:   &lt;para&gt;
1.152     spz       574:     Entry text goes here.  Manual pages can be referred to as <span class="quote">&#8220;<span class="quote">&amp;man.command.X;</span>&#8221;</span>,
1.90      jschauma  575:     email addresses as &lt;email&gt;full@address&lt;/email&gt;.
                    576:   &lt;para&gt;
1.129     kano      577:   &lt;/sect3&gt;</pre>
1.90      jschauma  578:   </li>
1.156     darcy     579: <li class="listitem">Run <code class="code">make</code>.</li>
1.82      jschauma  580: </ol></div>
                    581: </div>
                    582: 
1.164     tron      583: <div class="sect4">
1.91      wiz       584: <div class="titlepage"><div><div><h5 class="title">
                    585: <a name="adding-links"></a>Adding links from the main pages:</h5></div></div></div>
1.82      jschauma  586: 
                    587: <p>
1.155     wiz       588: By running <code class="code">make</code> from within htdocs/changes, you will automatically
1.149     jschauma  589: update <a class="ulink" href="../" target="_top">htdocs/index.html</a>.  No further action on your part
                    590: is required.
1.82      jschauma  591: </p>
1.53      jschauma  592: <p>
1.149     jschauma  593: Alternatively, you can run <code class="code">make index.html</code> from the htdocs toplevel
1.53      jschauma  594: directory.
1.82      jschauma  595: </p>
                    596: </div>
                    597: 
1.164     tron      598: <div class="sect4">
1.91      wiz       599: <div class="titlepage"><div><div><h5 class="title">
                    600: <a name="link-specific"></a>If you want to add a link from a port specific page:</h5></div></div></div>
1.82      jschauma  601: 
1.152     spz       602: <div class="orderedlist"><ol class="orderedlist" type="1">
                    603: <li class="listitem">Edit htdocs/ports/<span class="emphasis"><em>arch</em></span>/index.html, and search
1.99      jschauma  604:     for the '&lt;!-- news --&gt;' block.</li>
1.152     spz       605: <li class="listitem">Add a new entry to the subsequent list in the form:
1.99      jschauma  606:     <p>
                    607:     </p>
1.129     kano      608: <pre class="programlisting">&lt;dt&gt;&lt;b&gt;<span class="emphasis"><em>date</em></span>:&lt;/b&gt; <span class="emphasis"><em>title</em></span>
1.82      jschauma  609:     &lt;dd&gt;<span class="emphasis"><em>body of item</em></span>
1.129     kano      610:     &lt;p&gt;</pre>
1.6       abs       611: <p>
1.99      jschauma  612:     </p>
1.6       abs       613:     where
1.164     tron      614:     <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.152     spz       615: <li class="listitem">
1.82      jschauma  616: <span class="emphasis"><em>date</em></span> - Normally as YEAR.MONTH.DATE</li>
1.152     spz       617: <li class="listitem">
1.82      jschauma  618: <span class="emphasis"><em>title</em></span> - Freeform (short) text title</li>
1.152     spz       619: <li class="listitem">
1.99      jschauma  620: <span class="emphasis"><em>body of item</em></span> - Freeform text for the entry.
1.122     kano      621:         Can span multiple lines and may use HTML tags and links.</li>
1.82      jschauma  622: </ul></div>
                    623: </li>
                    624: </ol></div>
                    625: </div>
                    626: 
1.164     tron      627: <div class="sect4">
1.91      wiz       628: <div class="titlepage"><div><div><h5 class="title">
                    629: <a name="finally"></a>Finally:</h5></div></div></div>
1.82      jschauma  630: 
1.152     spz       631: <div class="orderedlist"><ol class="orderedlist" type="1">
                    632: <li class="listitem">You may want to <a class="ulink" href="#validate-html" target="_top">validate the
1.99      jschauma  633:     HTML</a> in your modified files.</li>
1.156     darcy     634: <li class="listitem">Check in the files.  The command <code class="code">make commit</code>, when
1.99      jschauma  635:     issued from the htdocs toplevel directory, will commit the main
1.149     jschauma  636:     index-page with a default message of "NEWS; regen".  If you would
1.156     darcy     637:     like to add a more specific message, use <code class="code">MSG="Added News regarding
                    638:      FooBar" make commit</code>.</li>
1.152     spz       639: <li class="listitem">If the news is noteworthy it is a good idea to submit it to some
1.155     wiz       640:     news sites, like
1.144     dsieger   641:     <a class="ulink" href="http://daily.daemonnews.org/add_story.php3" target="_top">Daily Daemonnews</a>,
                    642:     <a class="ulink" href="http://www.osnews.com/submit.php" target="_top">OSNews</a>,
                    643:     <a class="ulink" href="http://slashdot.org/submit.pl" target="_top">Slashdot</a>,
                    644:     <a class="ulink" href="http://www.newsforge.com/submit.pl" target="_top">Newsforge</a> and
                    645:     <a class="ulink" href="http://www.bsdforums.org/submitnews.php" target="_top">BSDForums</a>.
1.99      jschauma  646:    </li>
1.82      jschauma  647: </ol></div>
                    648: </div>
                    649: 
1.57      jschauma  650: 
1.94      jschauma  651: <h4 class="title">
                    652: <a name="adding-events"></a>Adding Events (<a href="#specific">top</a>)
                    653:   </h4>
1.82      jschauma  654: <p>
1.57      jschauma  655: The main index page also contains links to "Upcoming Events".  These links are
1.144     dsieger   656: updated much like the <a class="ulink" href="#adding-news-items" target="_top">News entries</a>:
1.82      jschauma  657: </p>
                    658: <p>
                    659:   </p>
1.129     kano      660: <pre class="programlisting">
1.82      jschauma  661: cd .../htdocs/gallery
1.90      jschauma  662: $EDITOR events.xml
1.129     kano      663: make events.html</pre>
1.82      jschauma  664: <p>
                    665: </p>
1.58      jschauma  666: 
1.82      jschauma  667: <p>
                    668:   </p>
1.129     kano      669: <pre class="programlisting">
1.82      jschauma  670: cd .../htdocs
1.149     jschauma  671: make index.html
1.129     kano      672: MSG="Added Event Foo" make commit</pre>
1.82      jschauma  673: <p>
                    674: </p>
1.57      jschauma  675: 
1.94      jschauma  676: <h4 class="title">
                    677: <a name="adding-mailinglists"></a>Adding to/editing the MailingLists page  (<a href="#specific">top</a>)
                    678:   </h4>
1.82      jschauma  679: <p>
1.156     darcy     680: If a mailing list is missing from the
1.144     dsieger   681: <a class="ulink" href="../mailinglists/" target="_top">MailingLists</a> page:
1.82      jschauma  682: </p>
1.152     spz       683: <div class="orderedlist"><ol class="orderedlist" type="1">
1.156     darcy     684: <li class="listitem">Edit the htdocs/mailinglists/index.xml and htdocs/mailinglists/list2group.xsl files.</li>
1.152     spz       685: <li class="listitem">Run the makefile in htdocs/mailinglists, it will generate the
1.156     darcy     686:     index.html.</li>
1.152     spz       687: <li class="listitem">Confirm the generated html is good.</li>
1.156     darcy     688: <li class="listitem">Commit the index.xml and list2group.xsl files.</li>
                    689: <li class="listitem">Regenerate the index.html file to include the proper
                    690:     "generated from" statement.</li>
                    691: <li class="listitem">Commit the generated index.html file.</li>
1.82      jschauma  692: </ol></div>
                    693: <p>
                    694: </p>
                    695: 
1.94      jschauma  696: <h4 class="title">
                    697: <a name="consultants"></a>Consultants for hire (<a href="#specific">top</a>)
                    698:   </h4>
1.82      jschauma  699: <p>
1.144     dsieger   700: Before adding an entry to the ``Consultants for hire'' page (<a class="ulink" href="../gallery/consultants.html" target="_top">gallery/consultants.html</a>), please ask
1.62      jschauma  701: that the person in question provides a link back to our homepage and/or
                    702: mentions NetBSD on their website.  Needless to say that you should make sure
                    703: that the URL given is active and accessible.
1.82      jschauma  704: </p>
1.62      jschauma  705: 
1.133     dsieger   706: </div></div></div>
                    707: <div class="navfoot"></div>
1.147     mishka    708: <div id="footer"><div id="footerContent"><center>
1.133     dsieger   709: <span class="footfeed"><a href="http://www.NetBSD.org/cgi-bin/feedback.cgi">
                    710:          Contact</a> |
1.142     kano      711:       </span><span class="footcopy"><a href="../about/disclaimer.html">
1.133     dsieger   712:       Disclaimer</a> |
                    713: 
1.165     mspo      714:       <span class="copyright">Copyright © 1994-2013 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.<br>NetBSD<sup>®</sup> is a registered trademark of The NetBSD
1.133     dsieger   715:        Foundation, Inc.</span>
1.147     mishka    716: </center></div></div>
1.82      jschauma  717: </div></body>
1.1       abs       718: </html>

CVSweb <webmaster@jp.NetBSD.org>