Adding a new Article

Imprint

Contents of this page

1   Initialisation of the new Page

1.1   Choosing the Page Template

Pages are usually included into the project at least using the filename comprised of their stamp. The contents of such stamped pages are no longer subject to change after being released, except for the style sheets and the drop-in content they are using. When a revision of the article has been released, a new stamp will be used for the next follow-up version of the article.

Additionally to the stamped pages there can be a so-called dynamic page for an article. This page always represents the last version of the article. Its name can either be chosen the same in all languages of the project, or can be chosen individually for each language.

When an article carries a dynamic page, in its ReST sources a link to that dynamic page needs to be defined, to be used in the footer. Such links also need to be established in all other articles referring to the dynamic page. In case the dynamic file name is equal for all languages, a multilingual interlaced page can use the same ReST code for all languages to establish the link. Otherwise, when the dynamic page is called different for individual languages, this choice needs to be represented in the interlaced ReST code.

So three page templates are given here:

  1. The stamp-only page template without any dynamic page:

    Page.rst without dynamic version
    
    .. include:: Symbols.rst
    .. include:: Roles.rst
    .. include:: History.rst
    .. include:: Articles.rst
    
    
    -en-
    Headline
    ########
    -de-
    Überschrift
    ###########
    -all-
    
    .. include:: Navbar-XXX.rst
    
    .. _last: STAMP_
    
    .. footer::
    
        .. container:: flexfooter
    
            -en-
            *Released <tba>.*
            -de-
            *Freigegeben am <tba>.*
    
            -all-
            |prev| | |next| | |last|_
    
  2. The template for pages with a dynamic page, carrying the same name in all languages:

    Page.rst with language-uniform filename for the dynamic version
    
    .. include:: Symbols.rst
    .. include:: Roles.rst
    .. include:: History.rst
    .. include:: Articles.rst
    
    
    -en-
    Headline
    ########
    -de-
    Überschrift
    ###########
    -all-
    
    .. include:: Navbar-XXX.rst
    
    .. _last: STAMP_
    .. _dyn: DYN.html
    
    .. footer::
    
        .. container:: flexfooter
    
            -en-
            *Released <tba>.*
            -de-
            *Freigegeben am <tba>.*
    
            -all-
            |prev| | |next| | |last|_ | |dyn|_
    
  3. A template for pages with a dynamic page whose filename can be different across languages:

    Page.rst with language-specific filename for the dynamic version
    
    .. include:: Symbols.rst
    .. include:: Roles.rst
    .. include:: History.rst
    .. include:: Articles.rst
    
    
    -en-
    Headline
    ########
    -de-
    Überschrift
    ###########
    -all-
    
    .. include:: Navbar-XXX.rst
    
    .. _last: STAMP_
    -en-
    .. _dyn: DYN-EN.html
    -de-
    .. _dyn: DYN-DE.html
    -all-
    
    .. footer::
    
        .. container:: flexfooter
    
            -en-
            *Released <tba>.*
            -de-
            *Freigegeben am <tba>.*
    
            -all-
            |prev| | |next| | |last|_ | |dyn|_
    

1.2   Preparation of the new Page

Rename the page template file, preferrably using a name ID STAMP NAME.rst.

Edit the new page source ID STAMP NAME.rst:

  1. Replace the headlines.

  2. Replace Navbar-XXX.rst by the appropriate navbar. For most of the articles, this will be Navbar-Articles.rst. Specialised navbars exist for the index, the imprint and the downloads; e.g. the downloads navbar is called Navbar-Downloads.rst.

  3. Replace STAMP in the _last link target (STAMP_) by the actual stamp of the article. Be sure to use the article's stamp, not that of the page.

    You can use bxclip on the article directory to place its stamp in the clipboard:

    $ bxclip <path/to/article>
    

    The path can be . or even .. in case you're in a subdirectory of the article directory.

  4. The link target _dyn needs adjustment in case the article features a dynamic page. When the link target differs from language to language, two target names DYN-EN and DYN-DE exist, which are used for the respective language. There exists only one target name DYN in case that the name is language-independent.

    The footer for articles with dynamic page features an additional entry |dyn|_, which carries the "_" suffix from the beginning. Initially, in the template it runs:

    |prev| | |next| | |last|_ | |dyn|_
    

    Examples for names of dynamic pages are downloads.html for a downloads page whose name is independent of the language, and imprint.html (English version) plus impressum.html (German version) for the imprint page whose name is language-dependent.

2   Registration of the new Article

Iterate the following steps for each language LG of the project:

  1. Having the article stamp in memory, add to /Sources/Compounds/LG/Articles.rst (replacing LG by the actual language, e.g. en):

    .. |ARTICLESTAMP| replace:: TITLE
    .. _ARTICLESTAMP:
    
  2. Now put the page's stamp in the clipboard by using bxclip on the new page file:

    $ bxclip <path/to/page.rst>
    

    and use it to complement the new registry entry in Articles.rst, s.t. it looks like:

    .. |ARTICLESTAMP| replace:: TITLE
    .. _ARTICLESTAMP: PAGESTAMP.html
    

You can now write |ARTICLESTAMP|_ in any page of the project to place a link with the language-specific article name as title and the article's current page as target.

3   Including the new Page

  1. Augment one of the .blox files in /Sources/Compounds/LG/ by:

    <Name> : <PAGESTAMP>.rst :: blox-rst2html
    

    The name of the .blox file chosen should correspond with the article's scope. For example, use Articles.blox for the articles carrying the actual contents of the project, Site.blox for the imprint and Online.blox for download pages.

  2. If the article shall additionally be made available by a dynamic page, add:

    <Name> (dyn) : <PAGESTAMP>.rst : <DYNAMIC>.rst : blox-rst2html
    
  3. In case the page depends on another navbar than Navbar-Articles.rst, add in all new inclusion lines (for the stamped page as well as possibly for the dynamic page):

    +Navbar-XXX.rst+
    

    where Navbar-XXX.rst is the navbar used.

    For example, the imprint will depend on Navbar-Imprint.rst, thus its stamped inclusion line should look like:

    Imprint +Navbar-Imprint.rst+ : <PAGESTAMP>.rst :: blox-rst2html
    

4   Compiling the Project

Apply bxcompose to the page's source file. This will place compounds named after the stamp of the new page in the language target directories LG/ within /Sources/Compounds/.

Reapply bxcompose after changes to the page's source file.

Point to the new article in existing pages as required, and compile your project. Thereby the new pages will be picked up for inclusion in the compilation result by means of the updated .blox file.