|
1 | | -# Introduction |
| 1 | +# CNF best practices |
2 | 2 |
|
3 | | -This repo is a scratch pad for a GDoc > Docx > AsciiDoc conversion workflow using a number of conversion steps. |
4 | | - |
5 | | -Tools used: Libre Office, Pandoc, Nebel, AsciiDoctor. |
6 | | - |
7 | | -**NOTE: This repo is a scratch pad only, content is not final or production ready, do not share** |
8 | | - |
9 | | -## Gdoc > Docx steps |
10 | | - |
11 | | -The GDoc file I reviewed had some mismatches in formatting which I tidied up. The pandoc conversion uses Document styles to apply formatting. Consistent Styles in GDoc mean the conversion is more consistent. |
12 | | - |
13 | | -* Download the [CNF GDoc](https://docs.google.com/document/d/1NmqbdTHll4kMamcaarCBagN7ZYlHysVtaRlolAu56R8/edit) as .docx > "Save as ... docx" |
14 | | -* Open the downloaded docx in libre Office, and clean up codeblocks (apply "Source Code" style to codeblocks), and definition list elements, etc using reference.docx as a formatting guide. |
15 | | -* Save docx updates as "Word docx 2007 compatible". |
16 | | - |
17 | | -## Pandoc conversion |
18 | | - |
19 | | -```cmd |
20 | | -pandoc -t asciidoc -f docx cnf-reqs_1.3.docx -o cnf-reqs_1.3.adoc --extract-media ./images --wrap=none |
21 | | -``` |
22 | | - |
23 | | -## Split single AsciiDoc file into topic modules + assembly |
24 | | - |
25 | | -```cmd |
26 | | -nebel split --legacybasedir ./ cnf-reqs_1.3_single.adoc |
27 | | -``` |
28 | | - |
29 | | -## Description of demo files |
30 | | - |
31 | | -* `cnf-reqs_1.3.docx` is a minimally modified docx version of the cnf-reqs GDoc. Main change is tidying up codeblocks using "Source Code" paragraph style. |
32 | | -* `cnf-reqs_1.3_single.adoc` is a cleaned up version of the pandoc conversion of `cnf-reqs_1.3.docx` |
33 | | -* `out/` contains a chunked version of the AsciiDoc files. **This is close to what the final conversion should look like.** |
34 | | -* `reference.docx` shows the supported styles for pandoc conversions. |
35 | | -* `reference.adoc` generated from `reference.docx` |
36 | | -* Single file is cut to assembly + out file using [nebel](https://github.com/fbolton/nebel#splitting-content) |
37 | | - |
38 | | -## AsciiDoc-side cleanup |
39 | | - |
40 | | -TODO: write a grep n replace script that does the following: |
41 | | - |
42 | | -* `____` > `` |
43 | | -* ` {blank}\n+\n` > ` ` |
44 | | -* Optional: `....\n` > `----\n` |
45 | | -* Fix xrefs |
46 | | -* Fix section titles, bullets, dl formatting |
47 | | -* Run output through choppy/nebel - make sensible length topics |
| 3 | +Provides guidance and best practices information for developing OpenShift applications that utialize cloud-native functions for high-performance workloads. |
0 commit comments