copyright: 2025 Marco de Beurs copyright: 2022 - 2024 Octrooicentrum Nederland license: | Licensed under the EUPL-1.2 or later.
You may obtain a copy of the licence at 'https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12'.
authors: Marco de Beurs, Peter van Dongen
title: Manual for building online documents date: 9-1-2025 ...
This manual will explain why and how the sources of both the software and contents of this system can be used.
The purpose of the system is twofold:
- Having an automated flexible publishing system.
- Having educational material for lecturing Intellectual Property.
This system has been build to support the educational department of the Dutch patent office (Octrooicentrum Nederland) in providing lecturing materials for students in the higher education. The materials can be customized for a particular lecture and can be quickly published with low effort.
However, the publishing system is not limited to educational material. It can be used for all kinds of documents necessary to be published in different formats such as pdf, web or epub. With some effort your own layout style or the layout style of your organisation can be used.
The system follows the COPE principle: Create Once, Publish Everywhere. And uses full automation for a short time to publish.
To minimize repeating work, as much as is possible is automated. It means that in this system the writer will only write the text (structured content) in markdown and will not have to be bothered with e.g. the layout, similar like e.g. LaTeX. Likewise a user who wants to publish a new version only has to define the new version and is not bothered with the publishing e.g. on a website.
The use of established and stable commom unix / linux software allows a future proof system that can be maintained without specific programming knowledge. This common unix / linux software works together to provide a static website (static site generator) and also provides documents in a printable form as pdf and documents for electronic reading (epub for ereader).
The content is directed to a general introduction into intellectual property and more specifically into patents.
The design of the system allows a quick creation of different versions with specific topics (e.g patents, trademarks, designs and copyright) and examples (e.g. for mechanical engineers, medtech and biotech) tailored to the needs of the readers.
Next to a general introduction also some documents that introduce the finding of patent documents by searching are available.
To allow the dissemination of information on intellectual property (which is a main objective of the dutch patent office) the documents made with this system are licensed under the creative commons license (CC-BY-SA).
To have an open collaboration of different organisations and individuals contributing to this system, the source files in this system are licensed as open source under the EUPL.
The goal of the building with the tools in this project, is to automate as much as possible to get the required documents / websites. The job of the author is to input the text and figures in a text file with markdown formatting and determine which text files together form a complete document.
Schematically:
text a -----+--+ +-> version A html
text b -----+ -----> version A ----> version A epub
text c -----+ | +-> version A pdf
text d -----+--+
text e -----+--+ +-> version B html
text f --------+---> version B ----> version B epub
text g --------+ +-> version B pdf
- Title page (A)
- Colophon (A)
- Table of contents (A)
- List of figures (A)
- List of videos (A)
- Text body with
- Chapters and other sections
- Annex (A)
- Glossary (A)
- Bibliography (A)
- Others
All the parts with (A) are automatically generated.
- Title page (A)
- Table of contents (A)
- Text body with
- Chapters and other sections
- Glossary (A)
- Bibliography (A)
- Others
All the parts with (A) are automatically generated.
Several html files with parts of the text body and glossary:
- Title of the part (A)
- Table of contents of the part (A)
- Part of the text body or glossary (A) and other annexes.
The parts for the html files are defined by the author. The different html files are automatically generated.
Other html files are generated to form index files with a table of contents.
All the parts with (A) are automatically generated.
All the documents will be generated for the different defined languages. At this moment the languages are Dutch and English.
The following standard (GNU) unix tools are used:
makethe GNU version >= 4.3 for proper parallel build of the grouped targets of the images from pdf documents. Older version complains, but will build correctly, just not efficiently.m4sedpandoc- with filter
gladtexto create pictures of formulas for epub. Needs python 3.
- with filter
- LaTeX (LuaLaTeX)
- with packages:
glossaries,glossaries-dutch,glossaries-english,colophon - with specific use of:
latexmkmakeindex
- xelatex
- BibLaTeX
- with packages:
dvisvgmpoppler-utilspdfinfopdftoppm
sasscas the sass compilerdateis used byCurrentDateinstruction. Needs the used local languages (nl_NL, en_BW) installed.CurrentDateis defined inpreincl.m4.awkis used for data processing.grepis used for data processing.
The versions made in .list files are transformed to the different targets that are needed. The targets are divided by language en by the type of publication. At this moment the target languages are Dutch nl and English en. The publication types are webpage: html, ebook: epub and pdf with videos: pdf.
So at this moment, one version is transformed into six targets.
The command make is used to build all the targets of all the versions.
It will first generate the different versions from the list and text files to intermediate markdown files in the mds directory.
The intermediate markdown files are then transformed by pandoc to the target versions. The target versions are located in the targets directory.
With make clean the builds can be removed.
The versions contain the specific subjects for a particular study or university or possibly another entity.
The different versions are defined in the .list files.
These .list files include the text files and are located in the versions directory.
In this directory also other list files, to be included in list files, can be stored. If these list files do not end in the specific .list, then these are not build as separate versions.
The contents of a subject is stored in several text files (.md suffix for markdown). The several text files are included by the list files to form a version.
Therefore a text file should contain the contents of a single subject or a part of a subject. In this way the same text file can be used to make different versions.
The text in these files is the markdown used by pandoc and additional instructions. For the use of markdown see the pandoc manual or search for markdown in general on the internet.
The text files are stored in the text directory.
Pictures and movies can be included. Only a limited set of types are allowed, because they have to be usable for all the different targets. Pictures should be .png or .jpg. Movies should be .mp4.
These files are to be put in the media directory.
Instead of directly writing a version in a .list file, it is possible to use a template to be able to generate a specific version.
A .list file will be generated from a .gen file. The name chosen for the .gen file will be the version name up to the targets.
The version will depend on the settings of the possible options in this file.
The Makefile, the m4 macro files and the readme are placed in the root directory.
In the following directories the different contents are located:
fonts
: The fonts used for the pdf version are located here.
latex
: The latex files for making the pdf versions are located here. Both permanent and temporary files. The permanent files are for example: begin_en.tex, begin_nl.tex, begin_all.tex, end.tex, settings.tex and multilanguage.sty.
latex/libs
: The place for libraries used for pictures.
media
: Location for pictures and movies.
pictures
: Location for Tikz pictures to be used for generating pictures.
pictures/libs
: Link to the latex/libs directory.
text
: All the files with the contents in markdown are located here.
versions
: The different versions in .list files are located here. Other lists can also be placed here. Also the .gen files for version generation and the corresponding .tpl template files are placed here.
webversions
: The different versions for a website in .list files are located here.
webtext
: Files specific for the html target are located here. For example the headerinclude.html for inclusion into the html target is located here.
data
: source and generated files from data are placed here. To be used by special AddMake instructions.
scss
: The source files (.scss used by sass) for the style sheets are put here.
scripts
: The place for javascript files for the html target.
The following directories are automatically created by make when not already present:
deps
: The place for automatically created dependency files.
css
: The style sheets are put here.
mds
: Place for temporary intermediate markdown files.
targets
: The different targets are put here.
targets/media
: link to the media directory.
targets/css
: link to the css directory.
targets/scripts
: link to the scripts directory.
epubimg
: The place for the images of the pages of pdf files. Only used for epub target.
web
: The place for generated index files for a website.
All the files ending with .scss, but not when starting with an underscore, located in the scss directory are transformed into .css files by sass.
The files starting with an underscore can be used for inclusion.
A different layout, than the default layout for the documents, can be used by defining the layout in the .list file with the instruction SetLayout(name).
The name is used to select files wherein the layout is defined. The SetLayout(name) should be placed before the title instructions, because the title instructions generate the first pages of the pdf document.
In the latex directory, the files begin*_nl.tex or begin*_en.tex are used to select the correct settings for the layout selected in the different languages. The * is replaced with name.
In the layout directory, the files title_*.m4 and titlesub_*.m4 are included to make a titlepage in LaTeX. The file htmlindex_*.md is included in the index file of a version for the website. Also here the * is replaced with name.
The variable LANGUAGES := in the makefile determines the languages of the targets.
Several settings and files should be available for the different languages:
- Several translations of text that are not written in the main text, but are used in the documents are defined in
translations.m4. - In the
latexdirectory differentbegin_*.texare used to set the correct language for the pdf versions. - Also in the
picturesdirectory differentbegin_*.texare used to set the correct language for the pdf versions. - The files
index_*_navbar.htmlin thewebtextdirectory define the navigation bar in the different languages of the website.
The makefile is used to automate the building of the targets. Automatic dependencies are generated for the included files, pictures and movies, so that only the part that changed will trigger a rebuild for that part.
all
: makes all targets. This is the default.
oud
: same as all, but with older style option for pandoc. Used for pre Opensuse 15.4.
clean
: removes target and intermediate files.
info
: makes info doc.
style
: makes css files from the .scss files in the scss directory.
webindex
: makes the index files for a website. From the web directory only if not invoked with website or websiteupdate.
The variable LANGUAGES := en nl determines the languages of the targets.
The variable EXPORTED_DOCS= $(MD_DOCS:.md=.html) $(MD_DOCS:.md=.pdf) $(MD_DOCS:.md=.epub) determines the type of the targets.
The variable StyleSheet := default.css determines the css file for the html targets.
Overview of the make proces:
*.gen *.tpl *.gen *.tpl
| |
| gen1.m4 | gen1.m4
| prelistdep.m4 | gen2.m4
| |
*_list.d *.list index_intro.md
| |
+-------------+ |
| | |
| | genindex.m4 |
| | |
| *_index.md |
| | |
| +--------------------+
| | genindex2.m4
| |
| index.md
| |
| | genindex3.m4
| |
| index_nl.md
| index_en.md
| |
| | pandoc
| |
| index.html
| index_en.html
|
+----------------------+
| |
V V
*.list *.md *.list *.md glossary.md
| | |
| predep.m4 | +---------------+-------------+
| predep1.m4 | preincl.m4 | | |
| | ju.m4 | preglosmd.m4 | glostolatex.m4
*.d | countchapter.sed | preincommon.m4| preincommon.m4
| | | |
*_en.md glossary_nogls.md | |
*_nl.md | glossary.tex |
*_all.md | |
| | |
+----------------------+--+----+------+ | |
| | | | +-----+--------+ |
| pictdep.m4 | | | | |
| | | | colofondata.m4 | glosmd.m4 |
| | | | translations.m4 | |
*_en_pict.d | | | | |
*_nl_pict.d --+ | | *_en_colofon.md *_en_1.glo |
*_all_pict.d | | | *_nl_colofon.md *_nl_1.glo |
| | | *_all_colofon.md *_all_1.glo |
V | | | |
pictures/*.tex | | getcites.sed | | makeindex |
| | | nocites.m4 | gloss_en.ist |
+-----------+ | | | gloss_nl.ist |
| | | *_en_cites.md | gloss_all.ist |
| cat | | *_nl_cites.md | |
| | | *_all_cites.md | |
*_en.tex | | *_en_1.gls |
*_nl.tex | | *_nl_1.gls |
*_all.tex | | *_all_1.gls |
| | | | |
| xelatex | +--------------------------+ | +---------------+
| | | +--+----+ |
*_en.xdv | | | |
*_nl.xdv | | | prein1.m4 |
*_all.xdv | | | |
| | | *_en_1.md |
| dvisvgm | | *_nl_1.md |
| | | *_all_1.md |
*_en.svg | | | |
*_nl.svg | | +----------------------+ |
*_all.svg | | | | glosmd.m4 |
| | | figuremd.m4 | |
+-----------+ | | pdfinfo | |
| | | rmpages.sed | |
| | | *_en.glo |
| cat | *_en_fignum.md *_nl.glo |
| | *_nl_fignum.md *_all.glo |
*_en_preview.tex | *_all_fignum.md | |
*_nl_preview.tex | | | makeindex |
*_all_preview.tex | | | gloss_en.ist |
| | +-----+ | gloss_nl.ist |
| xelatex | | | | gloss_all.ist |
| | | | epubpdfdep.m4 | |
*_en_preview.pdf | | | | |
*_nl_preview.pdf | | | | |
*_all_preview.pdf | | epubpdf.d -+ *_en.gls |
| | | *_nl.gls |
| | V *_all.gls |
| | | |
| | media/*.pdf | |
| | | | |
| | | pdftoppm | |
| | | | |
| | epubimg/*-01.png | |
| | | |
| | | |
+--------------------------+ | | |
| | +--+-------------------+----+--+------------+
| | | | |
| +---+---------+----+-----------------+ | | navbar.m4
| | | | | | navbar1.m4
| preinlatex.m4 | preinepub.m4 | preinhtml.m4 +-+ |
| gloslatex.m4 | glosepub.m4 | gloshtml.m4 | *_en_*_navbar.html
| links.m4 | novid.m4 | vid.m4 | *_nl_*_navbar.html
| preincommon.m4 | linksepub.m4 | linkshtml.m4 | *_all_*_navbar.html
| | figureepub.m4 | figurehtml.m4 | |
| | preincommon.m4 | preincommon.m4 | +------------+
| | | | |
| | | | htmlindex.m4 |
| | | | htmlindex1.m4 |
| | | | |
| | | *_en_index.md |
| | | *_nl_index.md |
| | | *_all_index.md |
| | | | |
| | | | preinhtml.m4 |
| | | | firsthtml.m4
| | | |
| | | *_en_index_html.md |
| | | *_nl_index_html.md |
| | | *_all_index_html.md |
| | | | |
| | | | |
| | | | +----------+
| | | | | |
| | | | pandoc |
| | | | |
| | | *_en_index.html |
| | | *_nl_index.html |
| | | *_all_index.html |
| | | |
*_en_latex.md *_en_epub.md *_en_html.md |
*_nl_latex.md *_nl_epub.md *_nl_html.md |
*_all_latex.md *_all_epub.md *_all_html.md |
| | | |
| pandoc | pandoc +---+--------+---------------+ |
| | | | | |
*_en_mid.tex *_en.epub | htmldep.m4 | | |
*_nl_mid.tex *_nl.epub | | | |
*_all_mid.tex *_all.epub *_en_html.d | | |
| *_nl_html.d | |
| *_all_html.d | firsthtml.m4 | splithtml.m4
| | |
| *_en_in_html.md *_en_part*_html.md
| cat begin_en/nl/all.tex * end.tex *_nl_in_html.md *_nl_part*_html.md
| *_all_in_html.md *_all_part*_html.md
| | |
| | | |
| | +-----------|---+------+
*_en.tex | | | |
*_nl.tex | pandoc | pandoc
*_all.tex | |
| *_en.html *_en_part*.html
| latexmk *_nl.html *_nl_part*.html
| latexmkrc *_all.html *_all_part*.html
|
*_en.pdf
*_nl.pdf
*_all.pdf
The same tools as described so far, can be used to have a website that will automatically update.
In the directory webversions the .list files of the courses to be publish can be placed.
If the specific make commands for the website are used, then only the versions in this directory will be made or updated.
The following options for make are specific to be used for a website.
website
: will make all targets with dependencies from the webversions directory.
websiteupdate
: will only make newly added versions from the webversions directory. The files for the website are only made the first time. A later text change will not be updated to the files on the website. This behaviour can be overwritten with the instruction WebAlwaysUpdate in the .list file.