#833 Improve the authoring instructions to be helpful to beginners.
Merged 8 months ago by tibbs. Opened 8 months ago by rombobeorn.
rombobeorn/packaging-committee readme  into  master

grammar and spelling
Björn Persson • 8 months ago  
Expanded the authoring instructions.
Björn Persson • 8 months ago  
file modified
+29 -5

@@ -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

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.

This is nice, thanks!

Pull-Request has been merged by tibbs

8 months ago
Metadata