replace html entities
This commit is contained in:
@@ -21,21 +21,21 @@ tags:
|
||||
- tutorial
|
||||
|
||||
---
|
||||
_Note: This guide is also available [in FSFE’s wiki][1] now, and it will be the only version maintained. So please head over to the wiki if you’re planning to follow this guide._
|
||||
_Note: This guide is also available [in FSFE’s wiki][1] now, and it will be the only version maintained. So please head over to the wiki if you’re planning to follow this guide._
|
||||
|
||||
Those who create, edit, and translate [FSFE websites][2] already know that the source files are XHTML files which are build with a XSLT processor, including a lot of custom stuff. One of the huge advantages from that is that we don’t have to rely on dynamic website processors and databases, on the other hand there are a few drawbacks as well: websites need a few minutes to be generated by the central build system, and it’s quite easy to mess up with the XML syntax. Now if an editor wants to create or edit a page, she needs to wait a few minutes until the build system has finished everytime she wants to test how the website looks like. So in this guide I will show how to build single websites on your own computer in a fraction of the FSFE’s system build time, so you’ll only need to commit your changes as soon as the file looks as you want it. All you need is a bit hard disk space and around one hour time to set up everything.
|
||||
Those who create, edit, and translate [FSFE websites][2] already know that the source files are XHTML files which are build with a XSLT processor, including a lot of custom stuff. One of the huge advantages from that is that we don’t have to rely on dynamic website processors and databases, on the other hand there are a few drawbacks as well: websites need a few minutes to be generated by the central build system, and it’s quite easy to mess up with the XML syntax. Now if an editor wants to create or edit a page, she needs to wait a few minutes until the build system has finished everytime she wants to test how the website looks like. So in this guide I will show how to build single websites on your own computer in a fraction of the FSFE’s system build time, so you’ll only need to commit your changes as soon as the file looks as you want it. All you need is a bit hard disk space and around one hour time to set up everything.
|
||||
|
||||
_The whole idea is based on what FSFE’s webmaster Paul Hänsch has coded and written. [On his blog][3] he explains the new build script. He explains how to build files locally, too. However, this guide aims to make it a bit easier and more verbose._
|
||||
_The whole idea is based on what FSFE’s webmaster Paul Hänsch has coded and written. [On his blog][3] he explains the new build script. He explains how to build files locally, too. However, this guide aims to make it a bit easier and more verbose._
|
||||
|
||||
Before we’re getting started, let me shortly explain the concept of what we’ll be doing. Basically, we’ll have three directories: _trunk_, _status_, and _fsfe.org_. Most likely you already have _trunk_, it’s a clone of the FSFE’s main SVN repository, and the source of all operations. All those files in there have to be compiled to generate the final HTML files we can browse. The location of these finished files will be _fsfe.org_. _status_, the third directory, contains error messages and temporary files.
|
||||
Before we’re getting started, let me shortly explain the concept of what we’ll be doing. Basically, we’ll have three directories: _trunk_, _status_, and _fsfe.org_. Most likely you already have _trunk_, it’s a clone of the FSFE’s main SVN repository, and the source of all operations. All those files in there have to be compiled to generate the final HTML files we can browse. The location of these finished files will be _fsfe.org_. _status_, the third directory, contains error messages and temporary files.
|
||||
|
||||
After we (1) created these directories, partly by downloading a repository with some useful scripts and configuration files, we’ll (2) build the whole FSFE website on our own computer. In the next step, we’ll (3) set up a local webserver so you can actually browse these files. And lastly we’ll (4) set up a small script which you can use to quickly build single XHTML files. Last but not least I’ll give some real-world examples.
|
||||
After we (1) created these directories, partly by downloading a repository with some useful scripts and configuration files, we’ll (2) build the whole FSFE website on our own computer. In the next step, we’ll (3) set up a local webserver so you can actually browse these files. And lastly we’ll (4) set up a small script which you can use to quickly build single XHTML files. Last but not least I’ll give some real-world examples.
|
||||
|
||||
### 1. Clone helper repository
|
||||
|
||||
Firstly, clone a [git repository][4] which will give you most needed files and directories for the further operations. It has been created by me and contains configuration files and the script that will make building of single files easier. Of course, you can also do everything manually.
|
||||
|
||||
In general, this is the directory structure I propose. In the following I’ll stick to this scheme. Please adapt all changes if your folder tree looks differently.
|
||||
In general, this is the directory structure I propose. In the following I’ll stick to this scheme. Please adapt all changes if your folder tree looks differently.
|
||||
|
||||
<pre class="lang:default highlight:0 decode:true">trunk (~700 MB): ~/subversion/fsfe/fsfe-web/trunk/
|
||||
status (~150 MB): ~/subversion/fsfe/local-build/status/
|
||||
@@ -47,15 +47,15 @@ To continue, you have to have _git_ installed on your computer (_sudo apt-get in
|
||||
|
||||
<pre class="lang:sh highlight:0 decode:true">git clone https://src.mehl.mx/mxmehl/fsfe-local-build.git ~/subversion/fsfe/local-build</pre>
|
||||
|
||||
Now we take care of _trunk_. In case you already have a copy of _trunk_ on your computer, you can use this location, but please do a _svn up_ beforehand and be sure that the output of _svn status_ is empty (so no new or modified files on your side). If you don’t have _trunk_ yet, download the repository to the proposed location:
|
||||
Now we take care of _trunk_. In case you already have a copy of _trunk_ on your computer, you can use this location, but please do a _svn up_ beforehand and be sure that the output of _svn status_ is empty (so no new or modified files on your side). If you don’t have _trunk_ yet, download the repository to the proposed location:
|
||||
|
||||
<pre class="lang:default highlight:0 decode:true">svn --username $YourFSFEUsername co https://svn.fsfe.org/fsfe-web/trunk ~/subversion/fsfe/fsfe-web/trunk</pre>
|
||||
|
||||
### 2. Build full website
|
||||
|
||||
Now we have to build the whole FSFE website locally. This will take a longer time but we’ll only have to do it once. Later, you’ll just build single files and not >14000 as we do now.
|
||||
Now we have to build the whole FSFE website locally. This will take a longer time but we’ll only have to do it once. Later, you’ll just build single files and not >14000 as we do now.
|
||||
|
||||
But first, we have to install a few applications which are needed by the build script (**Warning**: it’s possible your system lacks some other required applications which were already installed on mine. If you encounter any _command not found_ errors, please report them in the comments or by mail). So let’s install them via the terminal:
|
||||
But first, we have to install a few applications which are needed by the build script (**Warning**: it’s possible your system lacks some other required applications which were already installed on mine. If you encounter any _command not found_ errors, please report them in the comments or by mail). So let’s install them via the terminal:
|
||||
|
||||
<pre class="lang:default highlight:0 decode:true">sudo apt-get install make libxslt</pre>
|
||||
|
||||
@@ -65,11 +65,11 @@ Now we can start building.The full website build can be started with
|
||||
|
||||
<pre class="lang:default highlight:0 decode:true">~/subversion/fsfe/fsfe-web/trunk/build/build_main.sh --statusdir ~/subversion/fsfe/local-build/status/ build_into ~/subversion/fsfe/local-build/fsfe.org/</pre>
|
||||
|
||||
See? We use the build routine from _trunk_ to launch building _trunk_. All status messages are written to _status_, and the final website will reside in _fsfe.org_. Mind differing directory names if you have another structure than I do. This process will take a long time, depending on your CPU power. Don’t be afraid of strange messages and massive walls of text ;-)
|
||||
See? We use the build routine from _trunk_ to launch building _trunk_. All status messages are written to _status_, and the final website will reside in _fsfe.org_. Mind differing directory names if you have another structure than I do. This process will take a long time, depending on your CPU power. Don’t be afraid of strange messages and massive walls of text ;-)
|
||||
|
||||
After the long process has finished, navigate to the _trunk_ directory and execute _svn status_. You may see a few files which are new:
|
||||
|
||||
<pre class="lang:default highlight:0 decode:true">max@bistromath ~/s/f/f/trunk> svn status
|
||||
<pre class="lang:default highlight:0 decode:true">max@bistromath ~/s/f/f/trunk> svn status
|
||||
? about/printable/archive/printable.en.xml
|
||||
? d_day.en.xml
|
||||
? d_month.en.xml
|
||||
@@ -77,20 +77,20 @@ After the long process has finished, navigate to the _trunk_ directory and execu
|
||||
? localmenuinfo.en.xml
|
||||
[...]</pre>
|
||||
|
||||
These are leftover from the full website build. Because _trunk_ is supposed to be your productive source directory where you also make commits to the FSFE SVN, let’s delete these files. You won’t need them anymore.
|
||||
These are leftover from the full website build. Because _trunk_ is supposed to be your productive source directory where you also make commits to the FSFE SVN, let’s delete these files. You won’t need them anymore.
|
||||
|
||||
<pre class="lang:default highlight:0 decode:true">rm about/printable/archive/printable.en.xml d_day.en.xml d_month.en.xml d_year.en.xml localmenuinfo.en.xml
|
||||
rm tools/tagmaps/*.map</pre>
|
||||
|
||||
Afterwards, the output of _svn status_ should be empty again. It is? Fine, let’s go on! If not, please also remove those files (and tell me which files were missing).
|
||||
Afterwards, the output of _svn status_ should be empty again. It is? Fine, let’s go on! If not, please also remove those files (and tell me which files were missing).
|
||||
|
||||
### 3. Set up local webserver
|
||||
|
||||
After the full build is completed, you can install a local webserver. This is necessary to actually display the locally built files in your browser. In this example, I assume you don’t already have a webserver installed, and that you’re using a Debian-based operating system. So let’s install _lighttpd_ which is a thin and fast webserver, plus _gamin_ which _lighttpd_ needs in some setups:
|
||||
After the full build is completed, you can install a local webserver. This is necessary to actually display the locally built files in your browser. In this example, I assume you don’t already have a webserver installed, and that you’re using a Debian-based operating system. So let’s install _lighttpd_ which is a thin and fast webserver, plus _gamin_ which _lighttpd_ needs in some setups:
|
||||
|
||||
<pre class="lang:sh highlight:0 decode:true">sudo apt-get install lighttpd gamin</pre>
|
||||
|
||||
To make Lighttpd running properly we need a configuration file. This has to point the webserver to show files in the _fsfe.org_ directory. You already downloaded my recommended config file (_lighttpd-fsfe.conf.sample_) by cloning the git repository. But you’ll have to modify the path accordingly and rename it. So rename the file to _lighttpd-fsfe.conf_, open it and change following line to match the actual and absolute path of the _fsfe.org_ directory (~ does not work here):
|
||||
To make Lighttpd running properly we need a configuration file. This has to point the webserver to show files in the _fsfe.org_ directory. You already downloaded my recommended config file (_lighttpd-fsfe.conf.sample_) by cloning the git repository. But you’ll have to modify the path accordingly and rename it. So rename the file to _lighttpd-fsfe.conf_, open it and change following line to match the actual and absolute path of the _fsfe.org_ directory (~ does not work here):
|
||||
|
||||
<pre class="lang:default decode:true">server.document-root = "/home/USER/subversion/fsfe/local-build/fsfe.org"</pre>
|
||||
|
||||
@@ -102,19 +102,19 @@ Until you press Ctrl+C, you should be able to open your local FSFE website in an
|
||||
|
||||
### 4. Single page build script
|
||||
|
||||
Until now, you didn’t see much more than you can see on the original website. But in this step, we’ll configure and start using a Bash script (_fsfe-preview.sh_) I’ve written to make a preview of a locally edited XHTML file as comfortable as possible. You already downloaded it by cloning the repository.
|
||||
Until now, you didn’t see much more than you can see on the original website. But in this step, we’ll configure and start using a Bash script (_fsfe-preview.sh_) I’ve written to make a preview of a locally edited XHTML file as comfortable as possible. You already downloaded it by cloning the repository.
|
||||
|
||||
First, rename and edit the script’s configuration file _config.cfg.sample_. Rename it to _config.cfg_ and open it. The file contains all paths we already used here, so please adapt them to your structure if necessary. Normally, it should be sufficient to modify the values for _LOC_trunk_ (_trunk_ directory) and _LOC_out_ (_fsfe.org_ directory), the rest can be left with the default values.
|
||||
First, rename and edit the script’s configuration file _config.cfg.sample_. Rename it to _config.cfg_ and open it. The file contains all paths we already used here, so please adapt them to your structure if necessary. Normally, it should be sufficient to modify the values for _LOC_trunk_ (_trunk_ directory) and _LOC_out_ (_fsfe.org_ directory), the rest can be left with the default values.
|
||||
|
||||
Another feature of the fsfe-preview is to automatically check the XML syntax of the files. For this, _libxml2-utils_ has to be installed which contains _xmllint_. Please execute:
|
||||
|
||||
<pre class="lang:default highlight:0 decode:true">sudo apt-get install libxml2-utils</pre>
|
||||
|
||||
Now let’s make the script easy to access via the terminal for future usage. For this, we’ll create a short link to the script from one of the binary path directories. Type in the terminal:
|
||||
Now let’s make the script easy to access via the terminal for future usage. For this, we’ll create a short link to the script from one of the binary path directories. Type in the terminal:
|
||||
|
||||
<pre class="lang:default highlight:0 decode:true">sudo ln -s ~/subversion/fsfe/local-build/fsfe-preview.sh /usr/bin/fsfe-preview</pre>
|
||||
|
||||
From this moment on, you should be able to call _fsfe-preview_ from anywhere in your terminal. Let’s make a test run. Modify the XHTML source file contribute/contribute.en.xhtml and edit some obvious text or alter the title. Now do:
|
||||
From this moment on, you should be able to call _fsfe-preview_ from anywhere in your terminal. Let’s make a test run. Modify the XHTML source file contribute/contribute.en.xhtml and edit some obvious text or alter the title. Now do:
|
||||
|
||||
<pre class="lang:default highlight:0 decode:true">fsfe-preview ~/subversion/fsfe/fsfe-web/trunk/contribute/contribute.en.xhtml</pre>
|
||||
|
||||
@@ -131,7 +131,7 @@ Now open the mentioned URL <http://localhost:5080/contribute/contribute.en.html>
|
||||
|
||||
### Recommended workflows
|
||||
|
||||
In this section I’ll present a few of the cases you might face and how to solve them with the script. I presume you have your terminal opened in the _trunk_ directory.
|
||||
In this section I’ll present a few of the cases you might face and how to solve them with the script. I presume you have your terminal opened in the _trunk_ directory.
|
||||
|
||||
##### **Preview a single file**
|
||||
|
||||
@@ -143,30 +143,30 @@ The script detects whether the file has to be built with the XSLT processor (.xh
|
||||
|
||||
##### Copy many files at once
|
||||
|
||||
Beware that all files you added in your session have to be processed with the script. For example, if you create a report with many images included and want to preview it, you will have to copy all these images to the output directory as well, and not only the XHTML file. For this, there is the _–copy_ argument. This circumvents the whole XSLT build process and just plainly copies the given files (or folders). In this example, the workflow could look like the following: The first line copies some images, the second builds the corresponding XHTML file which makes use of these images:
|
||||
Beware that all files you added in your session have to be processed with the script. For example, if you create a report with many images included and want to preview it, you will have to copy all these images to the output directory as well, and not only the XHTML file. For this, there is the _–copy_ argument. This circumvents the whole XSLT build process and just plainly copies the given files (or folders). In this example, the workflow could look like the following: The first line copies some images, the second builds the corresponding XHTML file which makes use of these images:
|
||||
|
||||
<pre class="lang:default highlight:0 decode:true">fsfe-preview --copy news/2016/graphics/report1.png news/2016/graphics/report2.jpg
|
||||
fsfe-preview news/2016/news-20161231-01.en.xhtml</pre>
|
||||
|
||||
##### Syntax check
|
||||
|
||||
In general, it’s good to check the XHTML syntax before editing and commiting files to the SVN. The script _fsfe-preview_ already contains these checks but it’s good to be able to use it anyway. If you didn’t already do it before, install _libxml2-utils_ on your computer. It contains _xmllint_, a syntax checker for XML files. You can use it like this:
|
||||
In general, it’s good to check the XHTML syntax before editing and commiting files to the SVN. The script _fsfe-preview_ already contains these checks but it’s good to be able to use it anyway. If you didn’t already do it before, install _libxml2-utils_ on your computer. It contains _xmllint_, a syntax checker for XML files. You can use it like this:
|
||||
|
||||
<pre class="lang:default highlight:0 decode:true">xmllint --noout work.en.xhtml</pre>
|
||||
|
||||
If there’s no output (–noout), the file has a correct syntax and you’re ready to continue. But you may also see something like
|
||||
If there’s no output (–noout), the file has a correct syntax and you’re ready to continue. But you may also see something like
|
||||
|
||||
<pre class="lang:default highlight:0 decode:true">work.en.xhtml:55: parser error : Opening and ending tag mismatch: p line 41 and li
|
||||
</li>
|
||||
</li>
|
||||
^</pre>
|
||||
|
||||
In this case, this means that the <p> tag starting in line 41 isn’t closed properly.
|
||||
In this case, this means that the <p> tag starting in line 41 isn’t closed properly.
|
||||
|
||||
### Drawbacks
|
||||
|
||||
The presented process and script has a few drawbacks. For example you aren’t able to preview certain very dynamic pages or parts of pages, or those depending on CGI scripts. In most cases you’ll never encounter these, but if you’re getting active with the FSFE’s webmaster team it may happen that you’ll have to fall back on the standard central build system.
|
||||
The presented process and script has a few drawbacks. For example you aren’t able to preview certain very dynamic pages or parts of pages, or those depending on CGI scripts. In most cases you’ll never encounter these, but if you’re getting active with the FSFE’s webmaster team it may happen that you’ll have to fall back on the standard central build system.
|
||||
|
||||
Any other issues? Feel free to report them as they will help to improve FSFE’s editors to work more efficiently :-)
|
||||
Any other issues? Feel free to report them as they will help to improve FSFE’s editors to work more efficiently :-)
|
||||
|
||||
##### Changelog
|
||||
|
||||
|
||||
Reference in New Issue
Block a user