From dee01233fcf496f9f643fb3996a9b98a80638063 Mon Sep 17 00:00:00 2001 From: Brian E Carpenter Date: Wed, 19 Jul 2023 15:20:01 +1200 Subject: [PATCH] Fix new chapter Also fixed makebook to protect Contents.md from mdformat --- 9. Troubleshooting/9. Troubleshooting.md | 63 ++----------------- .../Advanced Troubleshooting.md | 3 +- 9. Troubleshooting/Tools.md | 3 +- Contents.md | 2 + utilities/makeBook.py | 8 +-- 5 files changed, 14 insertions(+), 65 deletions(-) diff --git a/9. Troubleshooting/9. Troubleshooting.md b/9. Troubleshooting/9. Troubleshooting.md index b6364b6..806d440 100644 --- a/9. Troubleshooting/9. Troubleshooting.md +++ b/9. Troubleshooting/9. Troubleshooting.md @@ -1,64 +1,9 @@ -# 99. Chapter Template +# 9. Troubleshooting -This chapter shows how to write a new chapter. It is intentionally listed in the contents of the book itself, and is intended to be a living chapter of a living book. You should also check [CONTRIBUTING](../CONTRIBUTING.md) and [LICENSE](../LICENSE.md) before contributing. +## [Advanced Troubleshooting](Advanced%20Troubleshooting.md) -The second section in this chapter shows how to write a new section. +## [Tools](Tools.md) -We use the GitHub dialect of Markdown. There is some information about this in the [Markdown Usage](Markdown%20Usage.md) section below, including how to include diagrams. - -The first line in this file is: - -~~~ - # 99. Chapter Template -~~~ - -and this file is '99. Chapter Template.md' in the chapter directory named '99. Chapter Template'. - -Start with the general intro for a chapter. Tell the reader what the chapter is all about. Then give a list of the sections. It would be possible to embed the sections right here, but maintenance by multiple authors will be easier with a separate file per section. So write the introductory text and then add a list of sections that you intend to write. For example, after the introduction, put: - -~~~ - ## First Section - ## Section Template - ## Last Section -~~~ - -Please keep the section names short. They are also used as filenames. The text of the section "Section Template" will be in a file called "Section Template.md". - -Please do not add text inside or after the list of sections. That will confuse everybody. - -Important: Markdown can't handle file names with spaces in them. When creating links, we have to replace spaces with \%20, or avoid spaces in the file names. So here is the template for the list of sections after inserting links: - -~~~ - ## [First Section](First%20Section.md) - ## [Section Template](Section%20Template.md) - ## [Last Section](Last%20Section.md) -~~~ - -That's a bit complicated, and since file names are case-sensitive, errors are easy to make. Therefore, there exists a Python program called makeBook, which can be run occasionally to -create such links automatically, and reconcile differences between the actual chapter contents and the main [Contents](../Contents.md) page. - -It does some other things as well, to help authors: - -1. If it finds a chapter in the main contents, but there is no corresponding chapter directory, it creates the latter with appropriate template files that the author(s) can edit. So adding ```25. Interesting Stuff``` at the obvious place in Contents.md would work. - -2. If it finds a section in a chapter introduction, but there is no corresponding Markdown file, it creates such a file. The author only has to add the content. - -3. If it finds a Markdown file in the chapter directory, but it's not in the chapter contents, -it adds it to the list of contents. - -4. It automatically inserts links at the bottom of each section pointing to the previous and next sections (if they exist) and back to the chapter introduction. - -5. It expands certain references, as explained in [Markdown Usage](Markdown%20Usage.md). - -makeBook has to be run on the main Github branch from time to time. At this writing, there is limited practical experience with this - patience, please. If it goes wrong, there is nothing that can't be fixed manually. The main rule is: don't mess with the automatically generated links. - -So, to repeat: add a new ## item to the chapter introduction, and makeBook will create the necessary .md file. Add a new .md file to the chapter directory, and makeBook will add it to the chapter contents. - -*Pro tip:* Renaming or deleting a section or chapter, or moving a section from one chapter to another, are not automated at present and will require a good deal of manual work. - -## [First Section](First%20Section.md) -## [Section Template](Section%20Template.md) -## [Markdown Usage](Markdown%20Usage.md) -## [Last Section](Last%20Section.md) + ### [Back to main Contents](../Contents.md) diff --git a/9. Troubleshooting/Advanced Troubleshooting.md b/9. Troubleshooting/Advanced Troubleshooting.md index 4724d9b..1387e57 100644 --- a/9. Troubleshooting/Advanced Troubleshooting.md +++ b/9. Troubleshooting/Advanced Troubleshooting.md @@ -3,4 +3,5 @@ Section text goes here -### [Previous](Markdown%20Usage.md) [Chapter Contents](99.%20Chapter%20Template.md) \ No newline at end of file + +### [Next](Tools.md) [Chapter Contents](9.%20Troubleshooting.md) diff --git a/9. Troubleshooting/Tools.md b/9. Troubleshooting/Tools.md index 9015bca..fd8ff7f 100644 --- a/9. Troubleshooting/Tools.md +++ b/9. Troubleshooting/Tools.md @@ -3,4 +3,5 @@ Section text goes here -### [Next](Section%20Template.md) [Chapter Contents](99.%20Chapter%20Template.md) \ No newline at end of file + +### [Previous](Advanced%20Troubleshooting.md) [Chapter Contents](9.%20Troubleshooting.md) diff --git a/Contents.md b/Contents.md index 183bb4d..e3f7f85 100644 --- a/Contents.md +++ b/Contents.md @@ -63,6 +63,8 @@ and a [citation index](https://github.com/becarpenter/book6/blob/main/Citex.md). * Deployment in the enterprise [9. Troubleshooting](9.%20Troubleshooting/9.%20Troubleshooting.md) +* Advanced Troubleshooting +* Tools [20. Further Reading](20.%20Further%20Reading/20.%20Further%20Reading.md) * RFC bibliography diff --git a/utilities/makeBook.py b/utilities/makeBook.py index b0af4c3..235d278 100644 --- a/utilities/makeBook.py +++ b/utilities/makeBook.py @@ -22,7 +22,7 @@ and inter-chapter links as far as possible.""" # Version: 2023-01-10 - fix bug when adding new chapter name to Contents.md # - enormous simplification of Contents creation # Version: 2023-05-20 - skip on-line check for RFC bibliography -# Version: 2023-07-18 - apply mdformat to changed files +# Version: 2023-07-19 - apply mdformat to changed files # - add global mdformat option # - add mitigations for SSL certs for URL checking @@ -119,7 +119,7 @@ def rf(f): return l -def wf(f,l): +def wf(f,l, mdf = True): """Write list of strings to file""" global written file = open(f, "w",encoding='utf-8') @@ -127,7 +127,7 @@ def wf(f,l): file.write(line) file.close() logit("'"+f+"' written") - if formatter and f.endswith(".md"): + if mdf and formatter and f.endswith(".md"): mdformat.file(f, options={"wrap":72}) logit("'"+f+"' md formatted") written +=1 @@ -617,7 +617,7 @@ for i in range(1,len(contents)): contents[i] += "\n" #and write it back -wf("Contents.md", contents) +wf("Contents.md", contents, mdf=False) ######### Close log and exit