Annotation of htdocs/developers/htdocs.xml, revision 1.3
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.3 ! symka 12: <config param="cvstag" value="$NetBSD: htdocs.xml,v 1.2 2004/11/16 01:45:58 jschauma Exp $"/>
! 13: <config param="rcsdate" value="$Date: 2004/11/16 01:45:58 $"/>
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
175: <code>.html</code> files.
176: </para>
177: <para>
178: After converting a file to XML, remember to add it to the
179: <code>htdocs/layout.xml</code> file and regenerate the website.
180: </para>
181: </sect3>
182:
183: <sect3 id="dotxml-files">
184: <title>Processing .xml (docbook-website) files</title>
185: <para>
186: In order to build .html files from .xml files, you will need at
187: least <pkg>textproc/libxslt</pkg> and <pkg>textproc/docbook-website</pkg>
188: installed. These are installed as part of <pkg>meta-pkgs/netbsd-www</pkg>
189: </para>
190: <para>
191: To regenerate, cd to htdocs/ and run
192: <para><programlisting>make ./autolayout.xml</programlisting></para>
193: Then run <code><emphasis role="bold">make</emphasis></code> in the target directory.
194: </para>
195: </sect3>
196:
197: <sect3 id="moving-files">
198: <title>Renaming or moving files</title>
199: <para>
200: In order to move or rename files within htdocs, the following procedure is
201: recommended:
202:
203: <itemizedlist>
204: <listitem>copy the file from the original location to new location</listitem>
205: <listitem>modify html of the original file:
206: <itemizedlist>
207: <listitem>include a
208: <code><META HTTP-EQUIV=Refresh CONTENT="5; URL=new-location"></code>
209: tag in the header</listitem>
210: <listitem>remove all content except the header and the footer</listitem>
211: <listitem>add a sentence saying that the page moved and hyperlink it to the new
212: location</listitem>
213: </itemizedlist></listitem>
214: <listitem>cvs add the new file</listitem>
215: <listitem>cvs commit the new file and the changes of the old file at the same
216: time, so we have some cvs reference of when and why things moved</listitem>
217: </itemizedlist>
218: </para>
219: </sect3>
220:
221: <sect3 id="flaglinks">
222: <title>What is the reasoning behind the flag links with empty.gif?</title>
223: <para>
224: Each NetBSD 'flag' links at the base of each page has:
225: <itemizedlist>
226: <listitem>href containing netbsd-banner with no alt tag</listitem>
227: <listitem>href containing empty gif with "NetBSD" alt tag and the
228: words "Home Page"</listitem>
229: </itemizedlist>
230: This has the effect of:
231: <itemizedlist>
232: <listitem>Making the "NetBSD Home Page" link a single link in lynx,
233: i.e. not a NetBSD link and a Home Page link.</listitem>
234: <listitem>In netscape, causing the additional text to be centered and
235: aligned "better" w.r.t the graphic. Without it, at least
236: in netscape, they show up at the bottom not centered
237: vertically, and abut the graphic (or, if you include spaces,
238: include nasty underlined blanks which looks broken).</listitem>
239: </itemizedlist>
240: It's a grotty hack, but it makes things look right.
241: </para>
242: </sect3>
243:
244: <sect3 id="webserver">
245: <title>How do the pages get to the web server, and when?</title>
246: <para>
247: The NetBSD webpages are stored in CVS in the "htdocs" repository.
248: For security reasons, the htdocs repository is copied (via rsync)
249: to www.NetBSD.org each hour, and the a local checkout is done from
250: that copy of the repository. The checked out tree can be found in
251: "<code>/NetBSD-www</code>". The repository is updated and checked out
252: every hour, about 40 minutes after the full hour (*:40). If you
253: make a commit to htdocs, it will take up to an hour before the
254: changes show up.
255: </para>
256: <para>
257: Note that there are several files like the Gnats database
258: (<ulink url="http://www.NetBSD.org/Gnats/"/>), the pkgsrc and source changes
259: in Changes/changes*.html and Changes/pkg-changes*.html, the RSS
260: files in Changes/rss-*.xml etc. that are not part of htdocs but
261: that get generated by various scripts out of cron jobs directly on
262: the web server. Check out "htutils/changes/*" to get access to the
263: scripts.
264: </para>
265: </sect3>
266:
267: </sect2>
268:
269: <sect2 id="specific">
270: <title>Adding to specific areas</title>
271:
272: <sect3 id="adding-gallery-entries">
273: <title>Adding to the 'Sites running NetBSD' gallery</title>
274: <para>
275: If you have a <code>NETBSD GALLERY ADDITION</code> email from the <ulink
276: url="../gallery/addsite.html">htdocs/gallery/addsite.html</ulink> page:
277: <orderedlist>
278: <listitem>Ensure you have perl installed</listitem>
279: <listitem>Save the message in your copy/paste buffer </listitem>
280: <listitem><code>cd htdocs/gallery</code></listitem>
281: <listitem><code>./addsite.pl</code>, paste the buffer, add a ^D, and answer '<code>y</code>' if it parsed OK.</listitem>
282: <listitem><code>cvs commit</code></listitem>
283: </orderedlist>
284: Alternatively you can manually edit <code>htdocs/gallery/sites.data</code>, and
285: run <code>make</code>.
286: </para>
287: </sect3>
288:
289: <sect3 id="adding-news-items">
290: <title>Adding News Items</title>
291: <para>
292: Most news items go into <ulink
293: url="../Changes/">htdocs/Changes/index.list</ulink> (see note on
294: <ulink url="#dotlist-files">.list files</ulink>). Changes affecting a
295: specific port should also be linked to from their htdocs/Port/*/ news section.
296: </para>
297: <para>
298: Important code news items should also be noted in the text
299: <currentsrc>doc/CHANGES</currentsrc>
300: file.
301: </para>
302: <para>Quick ``howto'' for the impatient (but please do read on for details):
303: <itemizedlist>
304: <listitem>cd htdocs/Changes</listitem>
305: <listitem>make update</listitem>
306: <listitem>${EDITOR} index.list</listitem>
307: <listitem>make</listitem>
308: <listitem>make MSG="I added important NEWS!" commit</listitem>
309: </itemizedlist>
310: </para>
311:
312: <sect4 id="before-anything">
313: <title>Before you do anything with htdocs:</title>
314: <orderedlist>
315: <listitem>Ensure you have perl installed for the <ulink url="#dotlist-files">.list
316: files</ulink>.</listitem>
317: <listitem>Check out <code>htdocs</code> from the CVS repository.</listitem>
318: <listitem>If you already have a copy of htdocs in your tree, make sure you update it
319: regularly. In particular, when adding news items, make sure that
320: gallery/events.* is up to date as well, as the events are pulled in from
321: there!</listitem>
322: </orderedlist>
323: </sect4>
324:
325: <sect4 id="change-entry">
326: <title>To add a change entry:</title>
327: <orderedlist>
328: <listitem>Edit htdocs/Changes/index.list and search for the first line
329: starting <DATE>.</listitem>
330: <listitem>Insert a new line of the form
331: <para><programlisting><DATE><emphasis>tag</emphasis> <emphasis>date</emphasis> - <emphasis>title</emphasis></programlisting></para>
332: where
333: <itemizedlist>
334: <listitem><emphasis>tag</emphasis> - A lowercase/number/hyphen identifier. eg: 'new-xx-driver'</listitem>
335: <listitem><emphasis>date</emphasis> - In the form DAY MONTH YEAR. eg: '23 Jan 1999'</listitem>
336: <listitem><emphasis>title</emphasis> - Freeform text for the entry title - can use \ to
337: escape the end of line.</listitem>
338: </itemizedlist>
339: </listitem>
340: <listitem>Add the body of the item. manual pages (eg: &man.ls.1;), and email
341: addresses (eg: <user@domain>) will be automatically expanded. Feel
342: free to use HTML tags, though this is not compulsory.</listitem>
343: <listitem>Run '<code>make</code>'</listitem>
344: </orderedlist>
345: </sect4>
346:
347: <sect4 id="adding-links">
348: <title>Adding links from the main pages:</title>
349: <para>
350: By running <code>make</code> from within htdocs/Changes, you will automatically
351: update <ulink url="../">htdocs/index.html</ulink> and the index pages of all supported
352: translations. No further action on your part is required.
353: </para>
354: <para>
355: Alternatively, you can run <code>make index</code> from the htdocs toplevel
356: directory.
357: </para>
358: </sect4>
359:
360: <sect4 id="link-specific">
361: <title>If you want to add a link from a port specific page:</title>
362: <orderedlist>
363: <listitem>Edit htdocs/Ports/<emphasis>arch</emphasis>/index.html, and search for the
364: '<!-- news -->' block.</listitem>
365: <listitem>Add a new entry to the subsequent list in the form:
366: <para>
367: <programlisting><dt><b><emphasis>date</emphasis>:</b> <emphasis>title</emphasis>
368: <dd><emphasis>body of item</emphasis>
369: <p></programlisting>
370: </para>
371: where
372: <itemizedlist>
373: <listitem><emphasis>date</emphasis> - Normally as YEAR.MONTH.DATE</listitem>
374: <listitem><emphasis>title</emphasis> - Freeform (short) text title</listitem>
375: <listitem><emphasis>body of item</emphasis> - Freeform text for the entry. Can span mutltiple
376: lines and may use HTML tags and links.</listitem>
377: </itemizedlist>
378: </listitem>
379: </orderedlist>
380: </sect4>
381:
382: <sect4 id="finally">
383: <title>Finally:</title>
384: <orderedlist>
385: <listitem>You may want to <ulink url="#validate-html">validate the HTML</ulink> in
386: your modified files.</listitem>
387: <listitem>Check in the files - do not forget any <code>.list</code> files will
388: update the matching <code>.html</code>. The command 'make commit', when
389: issued from the htdocs toplevel directory, will commit the main
390: index-page, Changes/index.* and all the translations index pages with
391: a default message of "NEWS; regen". If you would like to add a more
392: specific message, use 'MSG="Added News regarding FooBar" make
393: commit'.</listitem>
394: <listitem>If the news is noteworthy it is a good idea to submit it to some news
395: sites, like
396: <ulink url="http://daily.daemonnews.org/add_story.php3">Daily Daemonnews</ulink>,
397: <ulink url="http://www.osnews.com/submit.php">OSNews</ulink>,
398: <ulink url="http://slashdot.org/submit.pl">Slashdot</ulink>,
399: <ulink url="http://www.newsforge.com/submit.pl">Newsforge</ulink> and
400: <ulink url="http://www.bsdforums.org/submitnews.php">BSDForums</ulink>.</listitem>
401: </orderedlist>
402: </sect4>
403:
404: </sect3>
405:
406: <sect3 id="adding-events">
407: <title>Adding Events</title>
408: <para>
409: The main index page also contains links to "Upcoming Events". These links are
410: updated much like the <ulink url="#adding-news-items">News entries</ulink>:
411: </para>
412: <para>
413: <programlisting>
414: cd .../htdocs/gallery
415: $EDITOR events.list
416: make events</programlisting>
417: </para>
418:
419: <para>
420: Since the events are included on all the translations index pages, all these
421: pages need to be generated and committed as well. This can be achieved by
422: issuing the 'make index' command from the htdocs directory.
423: </para>
424: <para>
425: <programlisting>
426: cd .../htdocs
427: make index
428: MSG="Added Event Foo" make commit</programlisting>
429: </para>
430: </sect3>
431:
432: <sect3 id="adding-mailinglists">
433: <title>Adding to/editing the MailingLists page </title>
434: <para>
435: If a mailing-list is missing from the
436: <ulink url="../MailingLists/">MailingLists</ulink> page:
437: <orderedlist>
438: <listitem>Edit the htdocs/MailingLists/index.m4 file</listitem>
439: <listitem>Run the makefile in htdocs/MailingLists, it will generate the index.html</listitem>
440: <listitem>Confirm the generated html is good.</listitem>
441: <listitem>commit the index.m4 and index.html files.</listitem>
442: </orderedlist>
443: </para>
444: </sect3>
445:
446: <sect3 id="consultants">
447: <title>Consultants for hire</title>
448: <para>
449: Before adding an entry to the ``Consultants for hire'' page (<ulink
450: url="../gallery/consultants.html">gallery/consultants.html</ulink>), please ask
451: that the person in question provides a link back to our homepage and/or
452: mentions NetBSD on their website. Needless to say that you should make sure
453: that the URL given is active and accessible.
454: </para>
455:
456: </sect3>
457: </sect2>
458: </sect1>
459: </webpage>
CVSweb <webmaster@jp.NetBSD.org>