💄 Use better template semantics and add new capabilities

* Document requirements in schema
* Add support for non-generated example titles
* Escape example values for use in shell
* Rename "delete current value" to "reset to default value" to better explain what it does
This commit is contained in:
Yann Bertrand 2021-04-04 12:49:28 +02:00
parent 4b1493d5f6
commit 39cc31f013
10 changed files with 245 additions and 131 deletions

View file

@ -24,7 +24,7 @@ meta:
width=\\"740\\" height=\\"80\\" style=\\"height: auto\\"
/>
> Category description.
Category description.
"
`;
@ -48,7 +48,7 @@ meta:
---
# Category
> Category description.
Category description.
- [Page](./page.html)
"
@ -73,7 +73,7 @@ meta:
---
# Category
> Category description.
Category description.
- [Page 1](./page1.html)
- [Page 2](./page2.html)
@ -99,7 +99,7 @@ meta:
---
# Category 1
> Category 1 description.
Category 1 description.
- [Page](./page.html)
"
@ -124,7 +124,7 @@ meta:
---
# Category 2
> Category 2 description.
Category 2 description.
- [Page](./page.html)
"

View file

@ -19,15 +19,16 @@ meta:
---
# Page
> Page description.
Page description.
- **Tested on macOS**:
* Big Sur
- **Parameter type**: bool
## Set to \`true\` (default value)
\`\`\`bash
defaults write com.apple.category page -bool true
defaults write com.apple.category page -bool \\"true\\"
\`\`\`
<img
src=\\"./category-page-true.png\\"
@ -35,10 +36,10 @@ defaults write com.apple.category page -bool true
width=\\"600\\" height=\\"400\\" style=\\"height: auto\\"
/>
## Set to \`false\`
\`\`\`bash
defaults write com.apple.category page -bool false
defaults write com.apple.category page -bool \\"false\\"
\`\`\`
<img
src=\\"./category-page-false.png\\"
@ -46,13 +47,12 @@ defaults write com.apple.category page -bool false
width=\\"400\\" height=\\"200\\" style=\\"height: auto\\"
/>
## Read current value
\`\`\`bash
defaults read com.apple.category page
\`\`\`
## Delete current value
## Reset to default value
\`\`\`bash
defaults delete com.apple.category page
\`\`\`
@ -78,7 +78,7 @@ meta:
---
# Page
> Page description.
Page description.
- **Tested on macOS**:
* Big Sur
@ -88,32 +88,35 @@ meta:
* end
## Set to \`start\`
\`\`\`bash
defaults write com.apple.category page -string start
\`\`\`
- output when value is start
output when value is start
\`\`\`bash
defaults write com.apple.category page -string \\"start\\"
\`\`\`
## Set to \`middle\` (default value)
\`\`\`bash
defaults write com.apple.category page -string middle
\`\`\`
- output when value is middle
output when value is middle
\`\`\`bash
defaults write com.apple.category page -string \\"middle\\"
\`\`\`
## Set to \`end\`
\`\`\`bash
defaults write com.apple.category page -string end
\`\`\`
- output when value is end
output when value is end
\`\`\`bash
defaults write com.apple.category page -string \\"end\\"
\`\`\`
## Read current value
\`\`\`bash
defaults read com.apple.category page
\`\`\`
## Delete current value
## Reset to default value
\`\`\`bash
defaults delete com.apple.category page
\`\`\`
@ -139,7 +142,7 @@ meta:
---
# Page
> Page description.
Page description.
- **Tested on macOS**:
* Big Sur
@ -150,7 +153,7 @@ meta:
defaults read com.apple.category page
\`\`\`
## Delete current value
## Reset to default value
::: danger
This an alert message. <br> \`defaults command\`
:::
@ -179,32 +182,34 @@ meta:
---
# Page
> Page description.
Page description.
- **Tested on macOS**:
* Big Sur
- **Parameter type**: string
## Set to \`~/Desktop\` (default value)
\`\`\`bash
defaults write com.apple.category page -string ~/Desktop && killall App
\`\`\`
- output when value is ~/Desktop
output when value is ~/Desktop
\`\`\`bash
defaults write com.apple.category page -string \\"~/Desktop\\" && killall App
\`\`\`
## Set to \`~/Pictures\`
\`\`\`bash
defaults write com.apple.category page -string ~/Pictures && killall App
\`\`\`
- output when value is ~/Pictures
output when value is ~/Pictures
\`\`\`bash
defaults write com.apple.category page -string \\"~/Pictures\\" && killall App
\`\`\`
## Read current value
\`\`\`bash
defaults read com.apple.category page
\`\`\`
## Delete current value
## Reset to default value
\`\`\`bash
defaults delete com.apple.category page && killall App
\`\`\`
@ -230,7 +235,7 @@ meta:
---
# Page
> Page description.
Page description.
- **Tested on macOS**:
* Big Sur
@ -241,25 +246,27 @@ meta:
- [\`com.apple.category2 a-third-key\`](../../a-third-category/a-third-key.html#set-to-0.5) must be set to \`0.5\`
## Set to \`true\` (default value)
\`\`\`bash
defaults write com.apple.category page -string true && killall App
\`\`\`
- output when value is true
output when value is true
\`\`\`bash
defaults write com.apple.category page -string \\"true\\" && killall App
\`\`\`
## Set to \`false\`
\`\`\`bash
defaults write com.apple.category page -string false && killall App
\`\`\`
- output when value is false
output when value is false
\`\`\`bash
defaults write com.apple.category page -string \\"false\\" && killall App
\`\`\`
## Read current value
\`\`\`bash
defaults read com.apple.category page
\`\`\`
## Delete current value
## Reset to default value
\`\`\`bash
defaults delete com.apple.category page && killall App
\`\`\`
@ -285,32 +292,34 @@ meta:
---
# Page
> Page description.
Page description.
- **Tested on macOS**:
* Big Sur
- **Parameter type**: bool
## Set to \`~/Desktop\` (default value)
\`\`\`bash
defaults write com.apple.category page -bool ~/Desktop
\`\`\`
- output when value is ~/Desktop
output when value is ~/Desktop
\`\`\`bash
defaults write com.apple.category page -bool \\"~/Desktop\\"
\`\`\`
## Set to \`~/Pictures\`
\`\`\`bash
defaults write com.apple.category page -bool ~/Pictures
\`\`\`
- output when value is ~/Pictures
output when value is ~/Pictures
\`\`\`bash
defaults write com.apple.category page -bool \\"~/Pictures\\"
\`\`\`
## Read current value
\`\`\`bash
defaults read com.apple.category page
\`\`\`
## Delete current value
## Reset to default value
\`\`\`bash
defaults delete com.apple.category page
\`\`\`
@ -336,38 +345,38 @@ meta:
---
# Page
> Page description.
Page description.
- **Tested on macOS**:
* Big Sur
- **Parameter type**: float
## Set to \`0\` (default value)
\`\`\`bash
defaults write com.apple.category page -float 0
defaults write com.apple.category page -float \\"0\\"
\`\`\`
<video autoplay loop muted playsinline width=\\"750\\" height=\\"400\\" style=\\"max-width: 100%; height: auto\\">
<source src=\\"./category-page-0.mp4\\" type=\\"video/mp4\\">
Example output with value set to 0
</video>
## Set to \`0.5\`
\`\`\`bash
defaults write com.apple.category page -float 0.5
defaults write com.apple.category page -float \\"0.5\\"
\`\`\`
<video autoplay loop muted playsinline width=\\"720\\" height=\\"390\\" style=\\"max-width: 100%; height: auto\\">
<source src=\\"./category-page-0.5.mp4\\" type=\\"video/mp4\\">
Example output with value set to 0.5
</video>
## Read current value
\`\`\`bash
defaults read com.apple.category page
\`\`\`
## Delete current value
## Reset to default value
\`\`\`bash
defaults delete com.apple.category page
\`\`\`
@ -393,32 +402,34 @@ meta:
---
# Page 1
> Page 1 description.
Page 1 description.
- **Tested on macOS**:
* Big Sur
- **Parameter type**: bool
## Set to \`true\` (default value)
\`\`\`bash
defaults write com.apple.category page1 -bool true
\`\`\`
- output when value is true
output when value is true
\`\`\`bash
defaults write com.apple.category page1 -bool \\"true\\"
\`\`\`
## Set to \`false\`
\`\`\`bash
defaults write com.apple.category page1 -bool false
\`\`\`
- output when value is false
output when value is false
\`\`\`bash
defaults write com.apple.category page1 -bool \\"false\\"
\`\`\`
## Read current value
\`\`\`bash
defaults read com.apple.category page1
\`\`\`
## Delete current value
## Reset to default value
\`\`\`bash
defaults delete com.apple.category page1
\`\`\`
@ -444,32 +455,34 @@ meta:
---
# Page 2
> Page 2 description.
Page 2 description.
- **Tested on macOS**:
* Big Sur
- **Parameter type**: bool
## Set to \`true\`
\`\`\`bash
defaults write com.apple.category page2 -bool true
\`\`\`
- output when value is true
output when value is true
\`\`\`bash
defaults write com.apple.category page2 -bool \\"true\\"
\`\`\`
## Set to \`false\` (default value)
\`\`\`bash
defaults write com.apple.category page2 -bool false
\`\`\`
- output when value is false
output when value is false
\`\`\`bash
defaults write com.apple.category page2 -bool \\"false\\"
\`\`\`
## Read current value
\`\`\`bash
defaults read com.apple.category page2
\`\`\`
## Delete current value
## Reset to default value
\`\`\`bash
defaults delete com.apple.category page2
\`\`\`
@ -495,32 +508,34 @@ meta:
---
# Page
> Page description.
Page description.
- **Tested on macOS**:
* Big Sur
- **Parameter type**: bool
## Set to \`true\` (default value)
\`\`\`bash
defaults write com.apple.category1 page -bool true
\`\`\`
- output when value is true
output when value is true
\`\`\`bash
defaults write com.apple.category1 page -bool \\"true\\"
\`\`\`
## Set to \`false\`
\`\`\`bash
defaults write com.apple.category1 page -bool false
\`\`\`
- output when value is false
output when value is false
\`\`\`bash
defaults write com.apple.category1 page -bool \\"false\\"
\`\`\`
## Read current value
\`\`\`bash
defaults read com.apple.category1 page
\`\`\`
## Delete current value
## Reset to default value
\`\`\`bash
defaults delete com.apple.category1 page
\`\`\`
@ -546,32 +561,34 @@ meta:
---
# Page
> Page description.
Page description.
- **Tested on macOS**:
* Big Sur
- **Parameter type**: bool
## Set to \`true\`
\`\`\`bash
defaults write com.apple.category2 page -bool true
\`\`\`
- output when value is true
output when value is true
\`\`\`bash
defaults write com.apple.category2 page -bool \\"true\\"
\`\`\`
## Set to \`false\` (default value)
\`\`\`bash
defaults write com.apple.category2 page -bool false
\`\`\`
- output when value is false
output when value is false
\`\`\`bash
defaults write com.apple.category2 page -bool \\"false\\"
\`\`\`
## Read current value
\`\`\`bash
defaults read com.apple.category2 page
\`\`\`
## Delete current value
## Reset to default value
\`\`\`bash
defaults delete com.apple.category2 page
\`\`\`

View file

@ -23,7 +23,7 @@ meta:
/>
{{/ image }}
> {{{ description }}}
{{{ description }}}
{{# keys }}
- [{{ title }}](./{{ lowerCase key }}.html)

View file

@ -23,7 +23,7 @@ meta:
/>
{{/ image }}
> {{{ description }}}
{{{ description }}}
{{# keys }}
- [{{ title }}](./{{ lowerCase key }}.html)

View file

@ -16,7 +16,7 @@ meta:
---
# {{{ title }}}
> {{{ description }}}
{{{ description }}}
- **Testé sur macOS**:
{{# versions }}
@ -35,10 +35,16 @@ meta:
{{/ if }}
{{# examples }}
## Avec la valeur `{{{ value }}}`{{# if default }} (par défaut){{/ if }}
## {{# if title }}{{{ title }}}{{ else }}Avec la valeur `{{ value }}`{{/ if }}{{# if default }} (par défaut){{/ if }}
{{# if text }}
{{# text }}
{{{ . }}}
{{/ text }}
{{/ if}}
```bash
defaults write {{ ../domain }} {{ ../key }} -{{ ../param.type }} {{{ value }}}{{# if ../after }} &&
{{ ../after }}{{/ if }}
defaults write {{ ../domain }} {{ ../key }} -{{# if command }}{{ command }}{{ else }}{{ ../param.type }}{{/ if }} {{# each value }}{{{ shellescape this }}} {{/ each }}{{# if ../after }}&& {{ ../after }}{{/ if }}
```
{{# video }}
<video autoplay loop muted playsinline width="{{ width }}" height="{{ height }}" style="max-width: 100%; height: auto">
@ -54,17 +60,18 @@ defaults write {{ ../domain }} {{ ../key }} -{{ ../param.type }} {{{ value }}}{{
/>
{{/ image }}
{{# text }}
- {{{ . }}}
{{/ text }}
{{/ examples }}
## Lire la valeur courante
```bash
defaults read {{ domain }} {{ key }}
```
## Supprimer la valeur courante
## Remettre la valeur à l'état initial
{{# if deleteAlert }}
::: {{ deleteAlert.type }}
{{{ deleteAlert.message }}}
:::
{{/ if }}
```bash
defaults delete {{ domain }} {{ key }}{{# if after }} && {{ after }}{{/ if }}
```

View file

@ -16,7 +16,7 @@ meta:
---
# {{{ title }}}
> {{{ description }}}
{{{ description }}}
- **Tested on macOS**:
{{# versions }}
@ -35,9 +35,16 @@ meta:
{{/ if }}
{{# examples }}
## Set to `{{{ value }}}`{{# if default }} (default value){{/ if }}
## {{# if title }}{{{ title }}}{{ else }}Set to `{{ value }}`{{/ if }}{{# if default }} (default value){{/ if }}
{{# if text }}
{{# text }}
{{{ . }}}
{{/ text }}
{{/ if}}
```bash
defaults write {{ ../domain }} {{ ../key }} -{{ ../param.type }} {{{ value }}}{{# if ../after }} && {{ ../after }}{{/ if }}
defaults write {{ ../domain }} {{ ../key }} -{{# if command }}{{ command }}{{ else }}{{ ../param.type }}{{/ if }} {{# each value }}{{{ shellescape this }}} {{/ each }}{{# if ../after }}&& {{ ../after }}{{/ if }}
```
{{# video }}
<video autoplay loop muted playsinline width="{{ width }}" height="{{ height }}" style="max-width: 100%; height: auto">
@ -53,17 +60,13 @@ defaults write {{ ../domain }} {{ ../key }} -{{ ../param.type }} {{{ value }}}{{
/>
{{/ image }}
{{# text }}
- {{{ . }}}
{{/ text }}
{{/ examples }}
## Read current value
```bash
defaults read {{ domain }} {{ key }}
```
## Delete current value
## Reset to default value
{{# if deleteAlert }}
::: {{ deleteAlert.type }}
{{{ deleteAlert.message }}}

View file

@ -11,6 +11,9 @@ module.exports = ({ defaults, url }, templatesPath, destinationPath) => {
`${templatesPath}/page.md.handlebars`,
'utf8'
)
Handlebars.registerHelper('shellescape', function (value) {
return '"'+`${value}`.trim().replace(/(["'$`\\])/g,'\\$1')+'"'
});
const renderPage = Handlebars.compile(pageTemplate)
defaults.categories.forEach(({ folder, name, keys }) => {
if (keys === undefined) {
@ -18,6 +21,11 @@ module.exports = ({ defaults, url }, templatesPath, destinationPath) => {
}
keys.forEach(({ domain, ...page }) => {
page.examples.forEach(example => {
if (!Array.isArray(example.value)) {
example.value = [example.value]
}
})
const pageReadmeContent = renderPage({
...page,
folder,

View file

@ -547,9 +547,16 @@ categories:
param:
type: array
examples:
- value: '"ViewModel" "View"'
- command: array-add
value:
- ViewModel
- View
text: Ajoute les suffixes "ViewModel" et "View" (pratique pour les architectures Model-View-ViewModel (MVVM)).
- value: '"Router" "Interactor" "Builder"'
- command: array-add
value:
- Router
- Interactor
- Builder
text: Ajoute les suffixes "Router", "Interactor" et "Builder" (pratique pour les architectures RIB).
versions: [Catalina]
after: killall Xcode

View file

@ -69,23 +69,41 @@
"examples": {
"type": "array",
"items": {
"description": "Describes a sample `defaults write` command example.",
"type": "object",
"properties": {
"value": {
"anyOf": [
{"type": "boolean"},
{"type": "string"},
{"type": "integer"},
{"type": "number"}
"$ref": "#/definitions/value"
},
"command": {
"description": "The command used to set data when running `defaults write`. Must be valid for the parameter type and value. If not specified, the parameter type will be used.",
"type": "string",
"enum": [
"string",
"data",
"int",
"float",
"bool",
"date",
"array",
"array-add",
"dict",
"dict-add"
]
},
"default": {
"description": "If this command resets to the default setting.",
"type": "boolean"
},
"image": {
"$ref": "#/definitions/image"
},
"title": {
"description": "Human readable title for this example, will be autogenerated if not provided",
"type": "string"
},
"text": {
"description": "Human readable description of this example.",
"type": "string"
}
}
@ -100,6 +118,31 @@
"type": "string"
},
"uniqueItems": true
},
"requirements": {
"type": "array",
"items": {
"description": "Describes another defaults setting that is required for this one to work.",
"type": "object",
"properties": {
"folder": {
"description": "The `folder` of a category in the defaults file.",
"type": "string"
},
"key": {
"description": "The `key` of a key in the category in the defaults file",
"type": "string"
},
"name": {
"description": "The defaults domain + key.",
"type": "string"
},
"value": {
"description": "The required value",
"$ref": "#/definitions/value"
}
}
}
}
},
"required": [
@ -138,6 +181,26 @@
"height",
"width"
]
},
"value": {
"description": "The literal value or values passed to the `defaults write` command in the terminal.",
"anyOf": [
{"type": "boolean"},
{"type": "string"},
{"type": "integer"},
{"type": "number"},
{
"type": "array",
"items": {
"anyOf": [
{"type": "boolean"},
{"type": "string"},
{"type": "integer"},
{"type": "number"}
]
}
}
]
}
}
}

View file

@ -553,9 +553,18 @@ categories:
param:
type: array
examples:
- value: '"ViewModel" "View"'
- command: array-add
value:
- ViewModel
- View
title: Add "ViewModel" and "View"
text: Add the "ViewModel" and "View" counterpart suffixes (Useful for Model-View-ViewModel (MVVM) architectures).
- value: '"Router" "Interactor" "Builder"'
- command: array-add
value:
- Router
- Interactor
- Builder
title: Add "Router", "Interactor" and "Builder"
text: Add the "Router", "Interactor" and "Builder" counterpart suffixes (Useful for RIB architectures).
versions: [Catalina]
after: killall Xcode