]> Lady’s Gitweb - Wiki/blob - Sources/Meta/Editing.djot
A second sentence for Midekh
[Wiki] / Sources / Meta / Editing.djot
1 {v-short="Editing"}
2 # editing this wiki
3
4 This wiki follows proper wiki philosophy, meaning that ⓐ all content
5 is subject to change and deletion by members at any time, ⓑ it is
6 assumed that people will put the most time and effort into things
7 they are most passionate or knowledge·able about, ⓒ the
8 generally‐accepted _goal_ is in making the wiki _better_ or _more
9 interesting_ and not in being _right_ or _wrong_, and ⓓ the result
10 should be taken as a slightly‐inaccurate consensus opinion of the
11 current moment which captures nobody’s worldview correctly but
12 never·the·less is fun, useful, or meaningful to spend time with.
13 It should go without saying that nobody believes everything on this
14 site and everybody believes some of it.
15
16 Be aware of the [][Meta:Licence] for this site; when you contribute,
17 you do so under these terms.
18
19 Wiki editing is done using Git; the git repository is located at
20 `ssh://wiki@git.ladys.computer/srv/git/Wiki`.
21 Obviously, only people who have s·s·h keys registered with the `wiki`
22 user to be able to edit.
23 Registration is by invitation only.
24
25 The file structure of the wiki is as follows:8--:
26
27 ```
28 Sources/
29 ↳ Category/
30 ↳ Editor/
31 ↳ Meta/
32 ↳ Namespace/
33 ↳ Page/
34 ↳ Special/
35 ```
36
37 The directories inside of `Sources/` are the wiki
38 [Namespaces][Special:Namespaces]; `Pages/` is the namespace for
39 ordinary pages.
40 Pages are written in [Djot][]{title="Djot (/dʒɑt/)"} with support for
41 the additional features documented below.
42
43 Filenames…
44
45 - *must not* include spaces.
46 - _should_ be PascalCase.
47 - _should_ closely match the title of the page (but _need not_ match it
48 exactly).
49
50 They also need to end in the extension `.djot`.
51
52 The first thing you should do is set up one or more [Editor][Editor:]
53 pages describing yoursel{f∣ves}.
54
55 The website is rebuilt on every push; Git _should_ warn you if there
56 are any errors.
57 Contact me ([][@:Lady]{.sig}) if things go horribly wrong.
58
59 {#djot-ext}
60 ## extensions to the Djot syntax
61
62 {id="djot.links-internal" v-full="djot internal links"}
63 ### internal links
64
65 A reference link which contains a colon is an internal link.
66 Typically, you should not include link text and just let it be
67 autogenerated from the page title.
68
69 - For any page, its full reference is `[][NamespaceName:FileName]`.
70
71 - Some namespaces have an abbreviated syntax:8--:
72
73 - Pages in the `Page` namespace can be referred to as just
74 `[][:FileName]`.
75
76 - Namespaces themselves can be linked as `[][NamespaceName:]`; this
77 is short for `[][Namespace:NamespaceName]`.
78 *Namespace pages are not implemented yet.*
79
80 - Editor pages can be linked as `[][@:YourName]`.
81 Add the class `sig` to format the link as a signature.
82
83 - Category pages can be linked as `[][#:Category]`. *Category pages
84 are not implemented yet.*
85
86 - The `v` attribute can be used to select an alternate title for the
87 page.
88 For example, `[][:FileName]{v=plural}`.
89 Variant titles must be specified on the title of the page being
90 linked, for example `{v-plural=FileNames}`.
91
92 - To link a section within a page, follow its filename with a hash and
93 the section i·d: `[][:FileName#section]`.
94 *This isn’t implemented yet.*
95
96 - If a page doesn’t exist, it will generate a “redlink” to
97 [][Special:NotFound] and the page will appear on the list at
98 [][Special:ToDo].
99 *The latter isn’t implemented yet.*
100
101 {id="djot.links-external" v-full="djot external links"}
102 ### external links
103
104 For the most part these work exactly as expected.
105 Both reference links and inline links are allowed.
106
107 You should give external links a `@title`, like
108 `{title="Some External Document"}`.
109 This is used to generate the title to use for the link in the listing
110 at the bottom of the page.
111 If the title matches the link text, you can leave the link text blank,
112 as in `[](https://example.com){title="Example Page"}`:
113 [](https://example.com){title="Example Page"}.
114
115 {id="djot.other" v-full="other djot extensions"}
116 ### other stuff
117
118 - The `@as` attribute can be used on any element with children to
119 change what H·T·M·L element is used.
120 For example, the following is a citation: _My Citation_{as=cite}.
121 Here is a disclosure widget:8--:
122
123 {as=details}
124 ::::::::::::
125 {as=summary}
126 My Summary
127
128 My details for this widget.
129 ::::::::::::
130
131 - There are symbols defined for spaces, invisible characters, and a
132 couple of other conveniences.
133 You can view the full list [here][GitWikiWeb/config.yaml].
134 You can also escape any special character using the following
135 syntax:8--: `:U+####:` (where `####`:mathsp:=:mathsp:the
136 codepoint in hexadecimal).
137
138 {#bcp}
139 ## best practices
140
141 {id="bcp.writing" v-full="best practices while {writing ∣ editing}"}
142 ### while {writing ∣ editing}
143
144 - *Use Unicode* to the best of your ability.
145
146 - *Wrap lines* to (at most) 71 characters.
147
148 - *Indent with spaces,* not tabs.
149
150 - *Put each sentence on its own line.*
151 This helps to keep git diffs clean and means that only sentences, not
152 entire paragraphs, will need to be reflowed.
153
154 - *Don’t capitalize titles,* unless they begin with a proper noun.
155 (*Do* capitalize filenames.)
156
157 - *Sign opinions,* ideally with a link to your [Editor][Editor:]’s
158 page, like this: [][Editor:Lady]{.sig}.
159 This offers them some protection against other people removing them
160 just because they disagree.
161
162 - *Communicate in‐band,* again with signatures; if you want to talk
163 about the contents of a page, there is no better place to do that
164 than the page itself.
165
166 - *Feel free to copy·edit* other people’s words (including and up to
167 deleting and re·writing the whole thing), but *try to preserve
168 ideolect* (e·g don’t change someone else’s typography for no
169 reason).
170
171 {id="bcp.git" v-full="best practices using git"}
172 ### using git
173
174 - *Use descriptive commit names.*
175 These don’t have to be long, but they should be informative enough
176 that someone following the [Atom feed][] has a general idea of
177 what the change entails.
178
179 - *Rebase, don’t merge.*
180 We want to preserve a linear commit history.
181 You should probably set `git config --global pull.ff only` if you
182 haven’t already.
183
184 - *Only force push [with lease][git push --force-with-lease].*
185 Ideally, don’t force push at all, but there are some cases where it
186 might be necessary (e·g, if you accidentally make a merge commit).
187
188 - You can work on changes you don’t want to be live yet in a branch,
189 but *branching is discouraged* and it’s better to just work messily
190 on `live`.
191
192 [Atom feed]:
193 https://git.ladys.computer/Wiki/atom
194 [Djot]:
195 https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/maste
196 r/doc/syntax.html
197 [GitWikiWeb/config.yaml]:
198 https://git.ladys.computer/GitWikiWeb/blob/refs/heads/ladys:/config.y
199 aml
200 [git push --force-with-lease]:
201 https://git-scm.com/docs/git-push#Documentation/git-push.txt---no-for
202 ce-with-lease
This page took 1.019493 seconds and 5 git commands to generate.