README.md

   1 # OpenSSL web pages
   2
   3 OpenSSL web page sources are written in [Markdown], and possibly templated
   4 further using [Template Toolkit].
   5
   6 Plain Markdown files must have the filename suffix `.md`.\
   7 Templated Markdown files must have the filename suffix `.md.tt`.
   8
   9 For page breadcrumbs purposes, every Markdown file must start with the
  10 following YAML section, where `{name}` is replaced with the name this file
  11 shall have in its part of the breadcrumbs:
  12
  13 ``` yaml
  14 ---
  15 breadcrumb: {name}
  16 ---
  17 ```
  18
  19 In each directory where there are Markdown files, there must also be a file
  20 `dirdata.yaml`, containing common data for that directory, which affects the
  21 rendering of the sidebar and the common page breadcrumbs (the `breadcrumb`
  22 value in each file will be appended to them).  For example, in the directory
  23 `examples/`, one might imagine a `examples/dirdata.yaml` looking like this:
  24
  25 ``` yaml
  26 ---
  27 breadcrumbs: |
  28   [Home](..) : [Examples](.)
  29 sidebar: |
  30   # Examples
  31
  32   -   [One example](example1.html)
  33   -   [Another example](example2.html)
  34 ---
  35 ```
  36
  37 Please remember that all YAML *must* start and end with tripple dash lines
  38 (`---`).
  39
  40 Recommendations
  41 ---------------
  42
  43 -   Let [Markdown guide] be your guide for writing Markdown files.
  44     The [Markdown guide extended syntax] adds a lot of useful
  45     possibilities.
  46
  47     *If there's an alternative* that [Github Flavored Markdown]
  48     understands, use that, as that makes reviewing easier.
  49
  50     If there's a need that isn't covered by the [Markdown guide],
  51     refer to the [Pandoc User's Guide], or use HTML, whichever is
  52     clearer.
  53
  54 -   Surround any table with `<p>` and `</p>`, to make it distinct from
  55     paragraphs around it.
  56
  57 Building
  58 --------
  59
  60 The Markdown files are rendered into HTML using [Pandoc], see the
  61 [Pandoc User's Guide] for information on the Markdown syntax it
  62 understands and support.
  63
  64 Building the web pages is done through the `Makefile`, and requires
  65 a number of programs to be installed:
  66
  67 -   [Template Toolkit].  The Debian package is `libtemplate-perl`
  68 -   [Pandoc].  The Debian package is `pandoc`
  69 -   [OpenSSL::Query], see its README.md for installation instructions.
  70 -   `git`, `python3`, `wget`
  71
  72 It also requires a checkout of a number of repositories and branches.  Some
  73 of the repositories may need specific access.  The `Makefile` requires that
  74 they are all collected under one checkouts directory, with the following
  75 layout:
  76
  77 -   `data` (checkout of the `omc/data` repository)
  78 -   `general-policies`
  79     (checkout of <https://github.com/openssl/general-policies.git>)
  80 -   `technical-policies`
  81     (checkout of <https://github.com/openssl/technical-policies.git>)
  82 -   `openssl`
  83     (checkout of <https://github.com/openssl/openssl.git>,
  84     `master` branch)
  85 -   `openssl-3.1`
  86     (checkout of <https://github.com/openssl/openssl.git>,
  87     `openssl-3.1` branch)
  88 -   `openssl-3.0`
  89     (checkout of <https://github.com/openssl/openssl.git>,
  90     `openssl-3.0` branch)
  91 -   `openssl-1.1.1-stable`
  92     (checkout of <https://github.com/openssl/openssl.git>,
  93     `OpenSSL_1_1_1-stable` branch)
  94
  95 The checkouts directory can be given to `make` with the `CHECKOUTS`
  96 variable. It is important to use an absolute path:
  97
  98 ``` console
  99 $ make CHECKOUTS=/PATH/TO/checkouts
 100 ```
 101
 102 [Template Toolkit]: http://www.template-toolkit.org/
 103 [Pandoc]: https://pandoc.org/
 104 [Pandoc User's Guide]: https://pandoc.org/MANUAL.html#pandocs-markdown
 105 [Markdown guide]: https://www.markdownguide.org
 106 [Markdown guide extended syntax]: https://www.markdownguide.org/extended-syntax/
 107 [Github Flavored Markdown]: https://github.github.com/gfm/
 108 [OpenSSL::Query]: https://github.com/openssl/omc-tools/tree/master/OpenSSL-Query