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> >= 1.68.1 and
45: <pkg>textproc/docbook-website</pkg> >= 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 (Netbsd.org,
85: netbsd.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><sect[1-4]></code>
1.9 jschauma 115: as well as each <code><table></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>&</quote> with <quote>&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><sect1 role="toc"></programlisting>
131: This will generate a TOC listing all <code><sect2></code>s with a
132: bulleted list of its <code><sect3></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><META HTTP-EQUIV=Refresh CONTENT="5; URL=new-location"></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: <sect3 id="link-name>
1.11 jschauma 323: <title>XX Mon XXX - FREEFORM TITLE</title>
1.5 jschauma 324: <para>
325: Entry text goes here. Manual pages can be refered to as <quote>&man.command.X;</quote>,
326: email addresses as <email>full@address</email>.
327: <para>
328: </sect3></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 '<!-- news -->' block.</listitem>
352: <listitem>Add a new entry to the subsequent list in the form:
353: <para>
354: <programlisting><dt><b><emphasis>date</emphasis>:</b> <emphasis>title</emphasis>
1.1 jschauma 355: <dd><emphasis>body of item</emphasis>
356: <p></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>