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