Skip to content

Commit 72d2de0

Browse files
az0az0
committed
Add style guide; apply it, fix subtitles
- Add guidelines for writing. - Apply new guidelines. - Split titles (in front matter) to subtitles. - Fix rendering of subtitle. - Fix syntax of random data (in chaff article).
1 parent 579d258 commit 72d2de0

21 files changed

Lines changed: 418 additions & 234 deletions

‎README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,66 @@ bundle exec jekyll build
2323
3. Make the edits in your own repository.
2424
4. Submit a pull request to merge your changes.
2525

26+
27+
# Style guide
28+
29+
## Writing style
30+
31+
- Use sentence case for all headings.
32+
- Avoid em-dashes; use commas, colons, or rewrite the sentence.
33+
- Use the Oxford comma.
34+
- Write "for example" instead of "e.g."
35+
- Write "that is" instead of "i.e."
36+
- Omit "Microsoft" when referring to Windows.
37+
38+
## UI instructions
39+
40+
- Bold UI elements the user clicks, selects, or toggles:
41+
- buttons: click **Delete**
42+
- menu items: go to **Edit > Preferences**
43+
- tabs, labels, checkboxes: select the **Custom** tab
44+
- Code for text the user types: type `bleachbit --list`
45+
- Describe the action in plain English first, UI element second:
46+
- yes: click **Shred files**
47+
- no: **Shred files** should be clicked
48+
- Use "click" for buttons, "select" for menus/dropdowns,
49+
"check"/"uncheck" for checkboxes, "type" for keyboard input
50+
- Code for keyboard shortcuts: press `Ctrl+Z`, press `Shift+Delete`
51+
- Use `+` to join keys, no spaces
52+
- Capitalize key names: `Ctrl`, `Shift`, `Alt`, `Enter`, `Delete`
53+
54+
## Headings
55+
56+
- Set `title` and optionally `subtitle` in the front matter;
57+
the template renders both: do not repeat them in the body
58+
- Use `subtitle` for a tagline or scope note (one sentence max;
59+
okay to omit).
60+
- Do not write `#` (h1) in the body: the template renders it
61+
from `page.title`.
62+
- Start body headings at `##` (h2), then `###` (h3).
63+
- Do not skip levels (no h2 → h4).
64+
- Use sentence case for both title and subtitle (in front matter)
65+
and for body headings: `## Limits to know`, not `## Limits To Know`
66+
67+
## Horizontal rules
68+
69+
- Use `---` only for major structural breaks, not between every section
70+
- Do not use `---` immediately after a heading
71+
72+
## Formatting
73+
74+
- Use `-` for unordered lists, not `*`.
75+
- Use numbered lists for steps or sequences.
76+
- Use bullet lists for items that don't need numbering.
77+
- Wrap long lines to keep diffs readable.
78+
79+
## Capitalization of proper nouns
80+
81+
- BleachBit: always CamelCase
82+
- Winapp2: capitalized when referring to the community project
83+
- `winapp2.ini`: always lowercase in code ticks; it is a filename
84+
- Windows, Linux, macOS: follow each platform's own styling
85+
2686
# License
2787

2888
The documentation is under the GNU General Public License version 3 or later

‎_layouts/page.html‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,8 @@
44

55
<div class="page-header">
66
{% include ad.html %}
7-
<h1>{{ page.title }}
8-
{% if page.subtitle %}<small>{{ page.subtitle }}</small>{% endif %}
9-
</h1>
7+
<h1>{{ page.title }}</h1>
8+
{% if page.subtitle %}<p class="subtitle">{{ page.subtitle }}</p>{% endif %}
109
</div>
1110

1211
{{ content }}

‎_posts/2015-09-25-cleanerml.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
layout: page
3-
title: "CleanerML Introduction – Write Custom BleachBit Cleaners"
3+
title: "CleanerML introduction"
4+
subtitle: "Write custom BleachBit cleaners"
45
nav_title: "CleanerML Intro"
56
category: cml
67
date: 2000-01-01 00:01:00

‎_posts/2015-09-25-command-line-interface.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
layout: page
3-
title: "BleachBit Command Line Interface (CLI) – Usage & Options"
3+
title: "BleachBit command line interface"
4+
subtitle: "Usage and options"
45
nav_title: "CLI"
56
category: doc
67
date: 2015-09-25 23:27:26

‎_posts/2015-09-25-frequently-asked-questions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
layout: page
3-
title: "BleachBit FAQ – Frequently Asked Questions & Answers"
3+
title: "Frequently asked questions"
44
nav_title: "FAQ"
55
category: doc
66
date: 2000-01-25 23:30:16

‎_posts/2015-09-25-general-usage.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
layout: page
3-
title: "BleachBit General Usage Guide – Getting Started"
3+
title: "General usage"
4+
subtitle: "Getting started"
45
nav_title: "Usage"
56
category: doc
67
date: 2015-09-25 23:25:52

‎_posts/2015-09-25-preferences.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
layout: page
3-
title: "BleachBit Preferences – Settings & Configuration Guide"
3+
title: "Preferences"
4+
subtitle: "Settings and configuration"
45
nav_title: "Preferences"
56
category: doc
67
date: 2015-09-25 23:17:25

‎_posts/2015-09-25-running-from-source-code.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
layout: page
3-
title: "Running BleachBit from Source Code – Developer Setup Guide"
3+
title: "Running BleachBit from source code"
4+
subtitle: "Developer setup guide"
45
nav_title: "Source Code"
56
category: dev
67
date: 2015-09-25 23:40:58

‎_posts/2015-09-25-shred-files-and-wipe-disks.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
layout: page
3-
title: "How to Shred Files and Wipe Disks with BleachBit"
3+
title: "How to shred files and wipe disks"
44
nav_title: "Shred Files"
55
category: doc
66
date: 2015-09-25 23:33:58

‎_posts/2015-09-25-winapp2ini.md‎

Lines changed: 25 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,42 @@
11
---
22
layout: page
3-
title: "Winapp2.ini Guide – Extend BleachBit Cleaning on Windows"
3+
title: "Winapp2.ini Guide"
4+
subtitle: "Extend BleachBit cleaning on Windows"
45
nav_title: "Winapp2.ini"
56
category: doc
67
date: 2015-09-25 23:38:45
78
order: 8
89
---
910

10-
BleachBit imports cleaning rules from winapp2.ini files giving Windows users 2400+ additional cleaners (and growing) created by the community. [Piriform does not endorse importing "CCleaner data" into BleachBit](https://www.bleachbit.org/news/ccleaner-asks-bleachbit-remove-winapp2ini-importer).
11+
BleachBit imports cleaning rules from `winapp2.ini` files, giving Windows users
12+
2,400+ additional cleaners (and growing) created by the Winapp2 community.
1113

12-
If you are writing new cleaner definitions, it is recommended you write them in [CleanerML](cleanerml) instead of winapp2.ini format because CleanerML is cross-platform, not legally encumbered, and contains many features not available in winapp2.ini.
14+
[Piriform does not endorse importing "CCleaner data" into BleachBit](https://www.bleachbit.org/news/ccleaner-asks-bleachbit-remove-winapp2ini-importer).
1315

14-
### Automatically import Winapp2.ini
16+
If you are writing new cleaner definitions, write them in
17+
[CleanerML](cleanerml) instead of `winapp2.ini` format because CleanerML
18+
is cross-platform, not legally encumbered, and contains many features
19+
not available in `winapp2.ini`.
1520

16-
Check this box, and restart BleachBit to download the winapp2.ini file. Restart BleachBit again for it to take effect.
21+
## Automatically import winapp2.ini
1722

18-
![Download and update Winapp2.ini automatically: BleachBit 0.8.8 on Windows 7](https://lh6.googleusercontent.com/-LTmt1E95Ioo/TfgnJN7NiLI/AAAAAAAAC4A/qdNQcmMjpvI/s800/bleachbit-088-windows-7-preferences-general-highlight.png)
23+
To automatically download and update `winapp2.ini` cleaners:
1924

20-
### Manually import Winapp2.ini
25+
1. Check the box shown in the screenshot below.
26+
2. Restart BleachBit to download the `winapp2.ini` file.
27+
3. Restart BleachBit again for it to take effect.
2128

22-
To manually import winapp2.ini cleaners, simply do this:
29+
![Download and update Winapp2.ini automatically: BleachBit 0.8.8 on Windows 7](https://lh6.googleusercontent.com/-LTmt1E95Ioo/TfgnJN7NiLI/AAAAAAAAC4A/qdNQcmMjpvI/s800/bleachbit-088-windows-7-preferences-general-highlight.png)
2330

24-
1. Download a winapp2.ini file. The CCleaner community organically maintains various files: [winapp2.ini](https://github.com/MoscaDotTo/Winapp2/). This file is not created by endorsed by Piriform, maker of CCleaner. An alternative file [Winapp2.ini plus](https://github.com/bleachbit/winapp2.ini) contains additional entries for BleachBit.
25-
2. Place the winapp2.ini file in the right directory, which is most of the same directories as [CleanerML](cleanerml). If you install BleachBit (i.e., non-portable mode), below are the recommended directories. See [CleanerML storage](cleanerml) for more options.
26-
* Windows XP: ```C:\Documents and Settings\(username)\Application Data\BleachBit\Cleaners\```
27-
* Windows Vista/7: ```C:\Users\(username)\AppData\Roaming\BleachBit\Cleaners\```
28-
3. Restart BleachBit.
31+
## Manually import winapp2.ini
2932

33+
To manually import `winapp2.ini` cleaners:
3034

35+
1. Download a `winapp2.ini` file. The Winapp2 community organically maintains various files:
36+
[Winapp2](https://github.com/MoscaDotTo/Winapp2/). This file is not created or endorsed by
37+
Piriform, maker of CCleaner. An alternative file [winapp2.ini plus](https://github.com/bleachbit/winapp2.ini)
38+
is modified for BleachBit.
39+
2. Place the `winapp2.ini` file in the right directory, which is most of the same directories as
40+
[CleanerML](cleanerml). If you install BleachBit (i.e., non-portable mode), use
41+
the directory `C:\Users\(username)\AppData\Roaming\BleachBit\Cleaners\`
42+
3. Restart BleachBit.

0 commit comments

Comments
 (0)