3.5 KiB
The book6 utilities
makeBook
This program is applied to the entire book6 directory whenever significant changes have been made. The reader is assumed to have carefully read the Chapter Template chapter.
makeBook's functions include:
-
Update the global contents (
Contents.md) to reflect the actual chapter contents. -
Update the individual chapter files (
./ChapterName/ChapterName.md) to correspond to the global contents. -
Create any missing section files (
./ChapterName/SectionName.md). -
Reconcile discrepancies between the global contents, the chapter contents, and the actual section files. (Not all discrepancies can be automatically reconciled - makeBook will issue a warning if it detects such a case).
-
Resolve any raw citations (
{{something}}or{{{something}}}) into a complete markdown link ([something](URL)). -
Create and insert internal links (from a chapter file to the individual sections, from each section to its predecessor and successor, etc.)
-
Reformat markdown text if appropriate.
After updating a section, especially if adding a new citation
with {{ }} or {{{ }}}, it's appropriate to run makeBook.py
(Python 3; requires tkinter; uses mdformat if installed).
To make changes other than just updating an existing section, also see chapterReorg.
makeBook works roughly as follows, using a tkinter GUI, not standard input.
-
Request name of book6 directory from user. Normally this will be the local copy of the GitHub repo.
-
Determine whether automatic checking of RFC existence is possible. If makeBook cannot access a recent copy of the RFC index, this checking is impossible and it logs a warning.
-
Determine whether automatic checking of I-D existence is possible. If makeBook cannot access the current I-D index, this checking is impossible and book6 logs a warning.
-
Read in the existing main contents (Contents.md).
-
Convert any plain text chapter names to links.
-
Scan main contents and create any missing chapter directories and blank chapter files, build a chapter list, extract section lists for each chapter, and add any missing section names to the main contents.
-
For each chapter:
7.1 If there is a remaining discrepancy between the list of sections in the main contents and the section files actually present, log a warning that makeBook must be run again to resolve it. Also log a warning if there is an uppercase/lowercase discrepancy (which really needs manual fixing).
7.2 Create and initialize any missing section files.
7.3 If anything in the chapter file has changed during steps 7.1 and 7.2 , write it back.
7.4 For each section in the chapter:
7.4.1 Read in the markdown file, update internal links
if necessary, expand any {{ }} or {{{ }}} citations
as markdown links (but log a warning if this fails).
7.4.2. If anything in the section file has changed during step 7.4.1, write it back.
7.5. Read in the chapter markdown file (again),
expand any {{ }} or {{{ }}} citations as markdown links
(but log a warning if this fails), and write it back
if necessary.
- Finally, write back the main contents.
Note that expanding citations is done by the function expand_cites() which is straightforward but tedious to describe.
makeBook issues warnings to standard output but also to the file makeBook.log in the main book directory. This log should always be checked after a run!
makeIndex
TBD
RFCbib6
TBD