mirror of
https://github.com/becarpenter/book6.git
synced 2024-05-07 02:54:53 +00:00
4f196b1cd1
Corrected several citation issues. When baking, change blob into pilcrow because of LaTeX.
111 lines
4.3 KiB
Markdown
111 lines
4.3 KiB
Markdown
# Chapter Template
|
|
|
|
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](https://github.com/becarpenter/book6/blob/main/CONTRIBUTING.md)
|
|
and [LICENSE](https://github.com/becarpenter/book6/blob/main/LICENSE.md)
|
|
before contributing.
|
|
|
|
The second section in this chapter shows how to write a new section.
|
|
|
|
We use the GitHub dialect of Markdown. There is some information about
|
|
this in the [<ins>Markdown Usage</ins>](Markdown%20Usage.md) section
|
|
below, including how to include diagrams.
|
|
|
|
A chapter lives in its own directory, e.g. this chapter lives
|
|
in the directory `99. Chapter Template`. Of course, the spaces
|
|
are part of the directory name and the name is case-sensitive.
|
|
The introduction to the chapter (like this file) is a markdown
|
|
file with the same name again, e.g. `99. Chapter Template.md`.
|
|
|
|
The first line in this file is:
|
|
|
|
```
|
|
# Chapter Template
|
|
```
|
|
|
|
so that makes three repetitions of `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.
|
|
|
|
1. 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.
|
|
|
|
1. 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.
|
|
|
|
1. 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.
|
|
|
|
1. 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:_ Adding a new chapter, renaming or deleting a section or chapter, or moving a section from one chapter to another, etc., are not automated at present and may require a good deal of manual work. For that, see the
|
|
[special instructions](https://github.com/becarpenter/book6/blob/main/utilities/chapterReorg.md).
|
|
|
|
## [First Section](First%20Section.md)
|
|
|
|
## [Section Template](Section%20Template.md)
|
|
|
|
## [Markdown Usage](Markdown%20Usage.md)
|
|
|
|
## [Last Section](Last%20Section.md)
|
|
|
|
### [<ins>Back to main Contents</ins>](../Contents.md)
|