Source files of fsfe.org, pdfreaders.org, freeyourandroid.org, ilovefs.org, drm.info, and test.fsfe.org. Contribute: https://fsfe.org/contribute/web/ https://fsfe.org
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

707 lines
24 KiB

  1. \input texinfo @c -*-texinfo-*-
  2. @setfilename README.info
  3. @settitle Webmastering FSFE
  4. @setchapternewpage odd
  5. @set lastupdated $Id: README.texi,v 1.3 2006-05-08 14:31:35 reinhard Exp $
  6. @titlepage
  7. @title Webmastering FSFE
  8. @subtitle Last updated @value{lastupdated}
  9. @c Add yourself here if you add at least a couple of paragraphs of useful
  10. @c information. :-)
  11. @author Jonas �berg
  12. @page
  13. @vskip 0pt plus 1filll
  14. Last updated @value{lastupdated}
  15. @end titlepage
  16. @node Top, Webmastering, (dir), (dir)
  17. @top Webmastering FSFE
  18. This document contains a description of the FSFE web pages, both
  19. the practice of maintaining them, and that of generating them. It is hoped
  20. that this document will be continuously updated by the webmasters of FSF
  21. Europe as the web pages evolve. It was last updated @value{lastupdated}.
  22. If you find bugs in this file, or have other ideas on how to improve it;
  23. please commit your ideas to paper in the README.texi file in CVS. All other
  24. versions are automatically generated from the TexInfo source.
  25. @menu
  26. * Webmastering:: How to be a Webmaster in 10 easy steps
  27. * Translating:: Doing it all again, 10 times over
  28. * Building:: How to build the pages, in 10 less easy steps
  29. * Administrating:: How to handle hits
  30. * People:: Who did all this?
  31. * Guides:: Step-by-step guides to certain functions
  32. @detailmenu
  33. --- The Detailed Node Listing ---
  34. Webmastering
  35. * Focuses:: How the user finds information
  36. * Source files:: What files to edit
  37. * Editing:: How to actually edit them
  38. * Automatic updates:: Pages magically update themselves!
  39. * Special files:: How to work with the magic glue
  40. Building
  41. * Requirements:: What you must have to build the pages
  42. * Process:: How the build process works
  43. * build.pl:: How the build script works
  44. Administrating
  45. * Apache:: Apache installation
  46. * Perl:: Perl installation
  47. People
  48. * Webmasters:: List of current webmasters
  49. * Translators:: List of translators
  50. Guides
  51. * Posting news:: How to post news items
  52. * Adding a project:: How to add a project
  53. @end detailmenu
  54. @end menu
  55. @node Webmastering, Translating, Top, Top
  56. @chapter Webmastering
  57. This chapter will describe how to be a webmaster of FSFE. It will
  58. describe how the pages are envisioned, what files can be edited, how they
  59. should be edited and various other bits that are of particular interest
  60. to a webmaster.
  61. @menu
  62. * Focuses:: How the user finds information
  63. * Source files:: What files to edit
  64. * Editing:: How to actually edit them
  65. * Automatic updates:: Pages magically update themselves!
  66. * Special files:: How to work with the magic glue
  67. @end menu
  68. @node Focuses, Source files, Webmastering, Webmastering
  69. @section Focuses
  70. The FSFE web pages are divided into focuses. Each focus represents a
  71. view of the web tree that contains all the information of global importance,
  72. aswell as the information relevant to the focus. A focus is usually a
  73. geographic area, such as Germany or France. A visitor can choose which focus
  74. to browse the pages with and will see slightly different things depending
  75. upon their choices.
  76. The pages themselves always contain the same information, no matter what
  77. focus is selected. The only exception to this is pages which are automatically
  78. generated. The notable things that change depending upon focus is the menu,
  79. and which projects are displayed on the project pages. This makes it easy
  80. for people to find information relevant for their interest.
  81. @node Source files, Editing, Focuses, Webmastering
  82. @section Source files
  83. As a webmaster, about the only information one is usually interested in is
  84. the content of the pages. This content is in the files named @code{*.xhtml}.
  85. Each file contains an XML document, conforming to XHTML 1.0. These files
  86. are particularly easy to update, since they look very much like every other
  87. HTML file.
  88. The information in these files will be transformed by XSL to produce the
  89. finished web page. Be sure to maintain a correct structure in these files. It
  90. should be similar to this:
  91. @verbatim
  92. <?xml version="1.0" encoding="iso-8859-1" ?>
  93. <html>
  94. <head>
  95. <title>Some title</title>
  96. </head>
  97. <body>
  98. Content of the page
  99. </body>
  100. <timestamp>$Date: 2006-05-08 14:31:35 $ $Author: reinhard $</timestamp>
  101. </html>
  102. <!--
  103. Local Variables: ***
  104. mode: xml ***
  105. End: ***
  106. -->
  107. @end verbatim
  108. @node Editing, Automatic updates, Source files, Webmastering
  109. @section Editing
  110. Once you've gotten hold of the correct source file to edit, things should be
  111. smooth sailing. Just follow standard XHTML 1.0, and things will render
  112. well in most browsers. Also, do make sure that the file is able to be validated
  113. as an XHTML document. You can use the validator at
  114. @url{http://validator.w3.org/} if you're not sure. A source file can
  115. simply be uploaded to the validator and it should validate as XHTML
  116. 1.0 Transitional.
  117. There is a program in the CVS tree called @file{tools/validate.pl}. If
  118. you install the XML::LibXML Perl module, you can use that program to
  119. make sure that your pages at least parse as valid XML before you
  120. commit them to CVS.
  121. The XML::LibXML module can be found in the Debian package
  122. libxml-libxml-perl.
  123. You use the program like this (after having made a change to
  124. index.en.xhtml and index.fr.xhtml):
  125. @verbatim
  126. $ tools/validate.pl index.en.xhtml index.fr.xhtml
  127. @end verbatim
  128. If the program croaks, you need to fix the file before committing it
  129. to CVS. If it does not, chances are that the page will render
  130. nicely. It's still not guaranteed though, but it's a good enough
  131. guess.
  132. @node Automatic updates, Special files, Editing, Webmastering
  133. @section Automatic updates
  134. It's often the case that one wants to have certain pages updated
  135. automatically, for example to allow the front page list the latest
  136. five newsitems, or to have a list of projects automatically
  137. generated. There is a support system in the build process that will do
  138. these things in a general enough way to be useful for most tasks.
  139. This will be explained in more detailed in the section about building
  140. the web pages, but sufficiently to say, the process involves parsing
  141. XML data in an intermediate step, producing XHTML information, which
  142. is then fed to the main XSL transformation.
  143. For every page that is automatically updated, there exists two files;
  144. page.sources and page.xsl. The first file gives a list of all the XML
  145. source files that should be used as input. The format of this file is
  146. as follows:
  147. @verbatim
  148. directory/*/filename:focus
  149. @end verbatim
  150. Several lines of this type can exist in each sources file. The first
  151. part of the line is a filename glob. The above example would match the
  152. source files @code{directory/2001/filename.en.xml},
  153. @code{directory/duck/filename.fr.xml}, and so on, depending upon the
  154. language.
  155. The focus specifies for what focuses the source files should be
  156. included. This can be either @code{global}, which would cause the
  157. files to be included for all focuses, or a country specific two-letter
  158. tag to include it only for that specific focus.
  159. The XSL file takes the sum of all source files and should produce a
  160. valid XHTML document. Please see index.xsl, news/news.xsl and other
  161. files in CVS for an example of how this is done.
  162. For the webmaster, it's usually enough to note that the XHTML files
  163. should be updated as usual, and that the XML files contain the input
  164. to the automatic build process.
  165. @node Special files, , Automatic updates, Webmastering
  166. @section Special files
  167. There are several special files in CVS that a webmaster should care
  168. particularly for. Besides the file mentioned in the previous section
  169. about automatic updates, there exists a directory called tools/. This
  170. directory holds all kinds of tools used by the build process. It also
  171. contain information that relates to the menus and the static texts on
  172. the pages.
  173. @node Translating, Building, Webmastering, Top
  174. @chapter Translating
  175. As a translator, your job is to make sure that as many pages as
  176. possible have translations into your local language. The process of
  177. translating is simple; usually, you take the original file, translate
  178. the contents, and then save it under another filename, indicating the
  179. language you're translating into. For example, @file{eucd.en.xhtml}
  180. becomes @file{eucd.de.xhtml} for the German translation, and so on.
  181. The question that most often arises is; what should be translated?
  182. This is not a simple question to answer, and it's up to each
  183. translator to do the best possible job at deciding this. Here are some
  184. guidelines though:
  185. @enumerate
  186. @item
  187. Always make sure that the @file{texts-en.xml} file in tools/ are
  188. translated into your language. If you're making a German translation,
  189. you should name the resulting file @file{texts-de.xml}, and similarly
  190. for other languages. If this file is out of date, or not translated,
  191. some texts might appear in English on your pages, despite other
  192. translations.
  193. @item
  194. Keep up to date with the news items in @file{news/YEAR/} and
  195. @file{COUNTRY/news/YEAR/} (where YEAR is something like 2002 or 2003,
  196. and COUNTRY is a countrycode such as de, or fr). Make sure that every
  197. item is translated and put into the translated file.
  198. @item
  199. All projects have a file called @file{project.en.xml} in their root
  200. directory. Take care to keep these translated and updated.
  201. @item
  202. Aside from the above files, you should work on translating the most
  203. important pages first. What pages constitutes as important, apart from
  204. these guidelines, are left open. Please take care to keep all pages
  205. you translate updated though. If you have very little time to check
  206. for updates, it might make sense to translate pages that are not
  207. updated very frequently instead of those that is.
  208. @end enumerate
  209. @node Building, Administrating, Translating, Top
  210. @chapter Building
  211. This chapter of the FSFE webmastering manual will describe the
  212. steps involved in building the web pages from scratch. Normally, this
  213. is not something that anyone should have to bother about. As a
  214. webmaster and translator, it's sufficient to know how it works so that
  215. one can fix problems with it as they arise.
  216. Building a complete set of pages can take up to 15-20 minutes, so it
  217. should not be done frequently.
  218. There are several sections to this problem. The first one describes
  219. the software requirements that are needed to build the pages. The
  220. second describes the actual process of building pages, and the third
  221. describe the @file{build.pl} script that does the actual building.
  222. @menu
  223. * Requirements:: What you must have to build the pages
  224. * Process:: How the build process works
  225. * build.pl:: How the build script works
  226. @end menu
  227. @node Requirements, Process, Building, Building
  228. @section Requirements
  229. The build script is created using Perl and requires several Perl
  230. modules to function properly. Most of them are included in the
  231. standard Perl distribution, but a few are not.
  232. The non-standard modules that needs to be installed are:
  233. @itemize
  234. @item
  235. @file{File::Find::Rule}.
  236. This module is a simple interface to make recursive searches for
  237. files. It's used extensively by the build script. It does not exist in
  238. any known packages, so it needs to be installed from CPAN with the
  239. following command:
  240. @verbatim
  241. # perl -MCPAN -e 'install File::Find::Rule;'
  242. @end verbatim
  243. @item
  244. @file{XML::LibXSLT} and @file{XML::LibXML}.
  245. These modules are both wrappers to the GNOME projects libxml and
  246. libxslt libraries. They exists in the Debian packages
  247. libxml-libxml-perl and libxml-libxslt-perl.
  248. Version 1.50 of XML::LibXST and version 1.52 of XML::LibXML is known
  249. to work. Later versions should work too. Those versions are, as of
  250. this writing, found in the Debian testing distribution. The versions
  251. in Debian stable are slightly too old and the build script would have
  252. to be modified somewhat to work with those.
  253. @end itemize
  254. @node Process, build.pl, Requirements, Building
  255. @section Process
  256. The first point in understanding how the web pages work on a technical
  257. level is to understand how the build process works. There are two
  258. items that require additional explanations; translations and focuses.
  259. @itemize
  260. @item
  261. When we create the pages from their respective sources, we make sure
  262. that we produce files for all languages that we have translations
  263. into. If the source file does not exist in a particular language, we
  264. use the language of the original source file instead, and put a
  265. special marker on the page saying that a translation to the selected
  266. language could not be found.
  267. This means that links can point to, for example,
  268. @url{/help/help.de.html}, even if the help page does not have a German
  269. translation. This is mostly useful because it means that if all the
  270. links in help.de.html (despite that the content of the page might be
  271. in English), point to German pages, the user will retain his or her
  272. choice of language thruought the web site.
  273. The build script has a post-processing instruction that makes sure
  274. that links are changed to reflect this. This does mean that language
  275. negotiation does not work, as such. Language negotiation only works
  276. when someone visits the first page. Thereafter, the user will retain
  277. the selected language even if the preference in the browser is
  278. changed.
  279. This also means that if a user selects another language on our web
  280. pages, that language will be retained thruought the site, despite the
  281. preference of the users browser.
  282. @item
  283. Focuses are ment to aid visitors in finding the right information for
  284. their interest. At the moment, we have three focuses; Global, French,
  285. and German. More will be added as time permits.
  286. Every focus will always contain the information that is of global
  287. interest, but that information might be supplemented by localised
  288. information.
  289. The things that are ``focused'' today is news items on the front page,
  290. and the projects that are shown to a visitor.
  291. @end itemize
  292. Having noted that, we will turn our attention to the technical
  293. implementation of these things. The first thing we have in our hands
  294. is a source file, such as @file{help.en.xhtml}. The format of this
  295. file should be as follows:
  296. @verbatim
  297. <?xml version="1.0" encoding="iso-8859-1" ?>
  298. <html>
  299. <head>
  300. <title>FSFE - What needs to be done?</title>
  301. </head>
  302. <body>
  303. Some content for the page.
  304. </body>
  305. <timestamp>$Date: 2006-05-08 14:31:35 $ $Author: reinhard $</timestamp>
  306. </html>
  307. @end verbatim
  308. It's important to note that not all pages follow this convention. It's
  309. a nice gesture to make sure that they do, but the build script
  310. contains some magic to be able to parse and handle files in other
  311. (older) formats aswell.
  312. This source file needs additional information before it can be sent to
  313. the final XSL transformation. In particular, we need to know what
  314. translations exists for it, what the menu should look like for this
  315. page and some special static text strings for the page.
  316. The build process should find all this information and create a new
  317. document from the above, merged with the additional information. When
  318. finished, the result should look like this:
  319. @verbatim
  320. <?xml version="1.0" encoding="iso-8859-1" ?>
  321. <buildinfo>
  322. <trlist> <!-- All translations that this page exists in -->
  323. <tr id="sv">Svenska</tr>
  324. <tr id="en">English</tr>
  325. </trlist>
  326. <menuset> <!-- The menu items for the right hand bar -->
  327. <menu id="menu/about">/about/about.html</menu>
  328. </menuset>
  329. <textset> <!-- The static text set for this language -->
  330. <text id="menu/about">About</text>
  331. </textset>
  332. <document> <!-- The actual document, as read from the XHTML -->
  333. <head>
  334. <title>FSFE - What needs to be done?</title>
  335. </head>
  336. <body>
  337. Some content for the page.
  338. </body>
  339. <timestamp>$Date: 2006-05-08 14:31:35 $ $Author: reinhard $</timestamp>
  340. </document>
  341. </buildinfo>
  342. @end verbatim
  343. The translations are looked up in the filesystem. The menu is taken
  344. from file menu files in the @file{tools} directory. The texts are also
  345. taken from the text files in the @file{tools} directory. If possible,
  346. the build process must try to pick the text files for the language
  347. that it is currently building for. If they don't exist, it should fall
  348. back on the English texts.
  349. This is, unfortunately, not all information that the XSL
  350. transformation needs. It needs additional information about filenames
  351. and other things. We must add these attributes:
  352. @itemize
  353. @item
  354. buildinfo/@@original.
  355. This attribute gives the language code of the original document (en
  356. for most pages).
  357. @item
  358. buildinfo/@@filename.
  359. The XSL process is made self-aware with this tag. It includes the
  360. filename that we're currently building, but without language tag or
  361. the trailing @file{.html}.
  362. @item
  363. buildinfo/@@language.
  364. The language that we're currently building the page for.
  365. @item
  366. buildinfo/@@outdated.
  367. This attribute is set to ``yes'' if the original file is newer than
  368. this translation.
  369. @item
  370. document/@@language.
  371. Set to the language of the document. This might be different than the
  372. language of the page, if we could not find a proper translation.
  373. @end itemize
  374. With these addition, the result could look like this:
  375. @verbatim
  376. <?xml version="1.0" encoding="iso-8859-1" ?>
  377. <buildinfo original="en" filename="about/background"
  378. language="de" outdated="no">
  379. ...
  380. <document language="en">
  381. ...
  382. </document>
  383. </buildinfo>
  384. @end verbatim
  385. With all this information, the XSL transformation is ready to
  386. begin. The resulting buildinfo node is passed to the
  387. @file{fsfe-new.xsl} XSL file, which transforms the document into the
  388. final XHTML file that is put into the web tree. Observe that this is
  389. done once for every focus.
  390. And if you thought that that was it, you're in for a surprise now! We
  391. havn't even begun to mention automatically updated pages. Luckily,
  392. they are not very complex.
  393. If there exists a file, @file{name.xsl} in addition to the normal
  394. source files, @file{name.lang.xhtml}, this means that the page is
  395. updated automatically from the source files mentioned in
  396. @file{name.sources}.
  397. To unravel this mystery, we will first look at the sources file, which
  398. can take the following form:
  399. @verbatim
  400. projects/*/project:global
  401. de/projects/*/project:de
  402. @end verbatim
  403. The sources file contains a list of glob patterns and their respective
  404. focus. The special focus, ``global'', means that the source files
  405. matching that glob pattern, will be included for all focuses.
  406. When the build process creates an automatically updated page, it
  407. begins by picking out the glob patterns for the current focus and
  408. adding ``.lang.xml'' to each pattern, once for each language. All
  409. files that match that glob pattern are then assembled into one set.
  410. Note that if we're generating a page in German, and there does not
  411. exist a file, @file{projects/a/project.de.xml}, but there does exist a
  412. file @file{projects/a/project.en.xml}, the English version of the file
  413. will be included for completeness.
  414. Suppose we have two files with the following content:
  415. @verbatim
  416. <?xml version="1.0" encoding="iso-8859-1" ?>
  417. <newsset>
  418. <news date="2002-12-18">
  419. <title>..</title>
  420. <body>..</body>
  421. </news>
  422. <news date="2002-12-14">
  423. <title>..</title>
  424. <body>..</body>
  425. </news>
  426. </newsset>
  427. @end verbatim
  428. and
  429. @verbatim
  430. <?xml version="1.0" encoding="iso-8859-1" ?>
  431. <newsset>
  432. <news date="2002-12-20">
  433. <title>..</title>
  434. <body>..</body>
  435. </news>
  436. </newsset>
  437. @end verbatim
  438. The assembled file will look like this:
  439. @verbatim
  440. <?xml version="1.0" encoding="iso-8859-1" ?>
  441. <set>
  442. <news date="2002-12-18">...</news>
  443. <news date="2002-12-14">...</news>
  444. <news date="2002-12-20">...</news>
  445. </set>
  446. @end verbatim
  447. Note that we loose the name of the top node. This is irrelevant for
  448. the transformation and having a common name means that we can,
  449. theoretically, include sets of different names into the resulting
  450. output.
  451. This resulting file is then merged with the @file{file.en.xhtml} file
  452. before it is passed to @file{file.xsl} for transformation. The way it
  453. does this is to simply insert the <set> node as a child of the <html>
  454. node.
  455. This transformation MUST result in an XML file that can then be used
  456. as input to @file{fsfe-new.xsl}, which in turn produces the finished
  457. page.
  458. @node build.pl, , Process, Building
  459. @section build.pl
  460. The @file{build.pl} script implements the build process described in
  461. the previous section. It has not been extensively tested and has never
  462. been optimized for speed.
  463. The script reads files from the current directory and produces the
  464. resulting web tree in the directory specified. It currently accepts
  465. the following options:
  466. @itemize
  467. @item
  468. -q.
  469. Quiet more. This will cause the script to be quiet about everything
  470. except plain errors.
  471. @item
  472. -u.
  473. Update only. This can be used to speed up the processing a
  474. bit. Normally, the script will remove everything from the destination
  475. directory before creating new pages there. This will leave all files
  476. in their former destinations and only build them if they have been
  477. changed.
  478. @item
  479. -d.
  480. Print some debug information.
  481. @item
  482. -n.
  483. Dry-run only. Using this switch prevents the script from writing any
  484. information to disk. All pages are generated, but the results are
  485. discarded. Can be used to verify that a tree will build correctly.
  486. @item
  487. -o <directory>.
  488. This switch must be specified. It lets the script know to which
  489. directory it should write the finished pages. This top level directory
  490. will contain a secondary directory for each focus.
  491. @end itemize
  492. @node Administrating, People, Building, Top
  493. @chapter Administrating
  494. @menu
  495. * Apache:: Apache installation
  496. * Perl:: Perl installation
  497. @end menu
  498. @node Apache, Perl, Administrating, Administrating
  499. @section Apache
  500. @node Perl, , Apache, Administrating
  501. @section Perl
  502. @node People, Guides, Administrating, Top
  503. @chapter People
  504. @menu
  505. * Webmasters:: List of current webmasters
  506. * Translators:: List of translators
  507. @end menu
  508. @node Webmasters, Translators, People, People
  509. @section Webmasters
  510. @node Translators, , Webmasters, People
  511. @section Translators
  512. @node Guides, , People, Top
  513. @chapter Guides
  514. This chapter contains simple step-by-step guides to performing certain
  515. functions on the FSFE web site, such as posting news, adding new
  516. projects and so on.
  517. @menu
  518. * Posting news::
  519. * Adding a project::
  520. @end menu
  521. @node Posting news, Adding a project, Guides, Guides
  522. @section Posting news
  523. When you're posting a news item, you have a choice to make; should it
  524. be a global item, or a localised item? The decision you make will
  525. influence which directory to put the information in. For a global news
  526. item, you should place it in @file{news/} and @file{country/news/} for
  527. localised news.
  528. Each directory mentioned should have one subdirectory for each
  529. year. Those directories should contain files of the form
  530. @file{news.en.xml} which can contain any number of news items. An
  531. English version of the news files are mandatory.
  532. Global news will be included for every focus. Localised news only for
  533. each respective focus. A news item in @file{news.en.xml} can look like
  534. this:
  535. @verbatim
  536. <news date="2002-02-01">
  537. <title>Something happened</title>
  538. <body>
  539. Something happened today, but we're not quite sure what.
  540. </body>
  541. <link>http://www.example.com/</link>
  542. </news>
  543. @end verbatim
  544. Once this has been commited to CVS, the item will be included in the
  545. news listings once the next update has been run.
  546. @node Adding a project, , Posting news, Guides
  547. @section Adding a project
  548. As for news items, the location of a project depends on whether it is
  549. of global interest or a local project. Place a directory with all
  550. project information in the @file{projects/} or
  551. @file{country/projects/} hierarchy.
  552. In addition to a directory, decide on a classification for the project
  553. (one of community, legal, other and technical). Put that information
  554. in a @file{project.en.xml} file in the root directory of the project.
  555. @verbatim
  556. <?xml version="1.0" encoding="iso-8859-1" ?>
  557. <projectset>
  558. <project type="legal">
  559. <title>Some project</title>
  560. <description>
  561. A description of the project.
  562. </description>
  563. <link>/projects/some/project.html</link>
  564. </project>
  565. </projectset>
  566. @end verbatim