Ralf Zerres
88233508fe
All files have a strong relation to the book sources of the rust-lang project itself. This may help to lower the burden for intrested people to get involved in OrbTK as well as reuse workflow habits. * LICENSE-MIT: The projekt licensing terms * README.md: Github frontpage * CONTIRBUTING.md: Advises on howto help improving the book * style-guide.md: Advises on howto improve the readability of generated prose and code. * tools: layout helper scripts and rust-code * ci: continius integration helper scripts * .gitattributes: set git default behaviours * .gitignore: keep source tree sane * Cargo.toml: package dependencies * rustfmt.toml: formatting rules for rust code * book.toml: mdBook dependencies Signed-off-by: Ralf Zerres <ralf.zerres@networkx.de>
1.5 KiB
1.5 KiB
Style Guide
Prose
- Prefer title case for chapter/section headings, ex:
## Generating a Secret Numberrather than## Generating a secret number. - Prefer italics over single quotes when calling out a term, ex:
is an *associated function* ofrather thanis an ‘associated function’ of. - When talking about a method in prose, DO NOT include the parentheses, ex:
read_linerather thanread_line(). - Hard wrap at 80 chars
- Prefer not mixing code and not-code in one word, ex:
Remember when we wrote `use std::io`?rather thanRemember when we `use`d `std::io`?
Code
- Add the file name before markdown blocks to make it clear which file we're talking about, when applicable.
- When making changes to code, make it clear which parts of the code changed and which stayed the same... not sure how to do this yet
- Split up long lines as appropriate to keep them under 80 chars if possible
- Use
bashsyntax highlighting for command line output code blocks
Links
Once all the scripts are done:
- If a link shouldn't be printed, mark it to be ignored
- This includes all "Chapter XX" intra-book links, which should be links for the HTML version
- Make intra-book links and stdlib API doc links relative so they work whether the book is read offline or on docs.rust-lang.org
- Use markdown links and keep in mind that they will be changed into
text at *url*in print, so word them in a way that it reads well in that format