| |
@@ -1,8 +1,8 @@
|
| |
# Fedora Packaging Committee
|
| |
|
| |
- Welcome! This is the pagure instance for the Fedora Packaging Committee.
|
| |
+ Welcome! This is the Pagure instance for the Fedora Packaging Committee.
|
| |
|
| |
- The pagure repository is used to store source of Packaging Guidelines,
|
| |
+ The Pagure repository is used to store the source of Packaging Guidelines,
|
| |
track related issues
|
| |
and accept changes via pull requests.
|
| |
|
| |
@@ -15,7 +15,31 @@
|
| |
|
| |
## Packaging Guideline Development
|
| |
|
| |
- ### Building and viewing the guidelines locally
|
| |
+ ### Checking the Effect of Your Changes
|
| |
+
|
| |
+ To quickly check whether the changes you have made to a .adoc file
|
| |
+ cause the desired changes to the HTML code,
|
| |
+ use Asciidoctor.
|
| |
+ It is in the package rubygem-asciidoctor,
|
| |
+ and is, despite the package name, usable from a command prompt:
|
| |
+
|
| |
+ ```
|
| |
+ $ asciidoctor path/to/file.adoc
|
| |
+ ```
|
| |
+
|
| |
+ This will generate an HTML file corresponding to the input file.
|
| |
+ The style will differ
|
| |
+ but the HTML code as such is supposed to match what will end up on the website,
|
| |
+ allowing you to see whether the Asciidoc code works as you intended.
|
| |
+
|
| |
+ ### Building the Whole Set of Guidelines
|
| |
+
|
| |
+ For building the whole set of guidelines locally
|
| |
+ and viewing them in the same style as on the website,
|
| |
+ there is a container-based build procedure.
|
| |
+ This will download and execute container blobs containing Antora,
|
| |
+ and produce a complete set of HTML documents and stylesheets,
|
| |
+ which can then be browsed through a temporary HTTP server.
|
| |
|
| |
Prerequisites:
|
| |
|
| |
@@ -23,7 +47,7 @@
|
| |
* `podman`
|
| |
* `python3`
|
| |
|
| |
- Run following commands and open http://localhost:8000/
|
| |
+ Run the following commands and open http://localhost:8000/
|
| |
|
| |
```
|
| |
$ make
|
| |
@@ -33,7 +57,7 @@
|
| |
### Writing
|
| |
|
| |
[Antora](https://antora.org/) is used for
|
| |
- managing the various documents which comprise the guideliens
|
| |
+ managing the various documents which comprise the guidelines
|
| |
and integrating them into the rest of Fedora Documentation.
|
| |
|
| |
The guidelines themselves are written in
|
| |
rombobeorn
commented 5 years ago
These are the instructions that would have saved me from failing the first time I tried to help with the conversion to Asciidoc (plus some grammar and spelling fixes).
This amends the guidelines authoring instructions to:
· Recommend Asciidoctor as a lightweight way of previewing one's changes.
· Point out that there is a command-line program in rubygem-asciidoctor.
· Explain how the purpose of the container-based method differs from the purpose of the Asciidoctor method.
· Mention that the makefile will download container blobs.