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