From: Lady Date: Fri, 28 Jul 2023 05:19:31 +0000 (-0700) Subject: Add initial editing guidelines X-Git-Url: https://git.ladys.computer/Wiki/commitdiff_plain/8048beec7d5f0977f1f680df616e26dca54e7fe0?ds=sidebyside Add initial editing guidelines These still need work, but in the spirit of Wiki·ing, I’m getting them out there. --- diff --git a/Sources/Meta/Editing.djot b/Sources/Meta/Editing.djot new file mode 100644 index 0000000..c9bde40 --- /dev/null +++ b/Sources/Meta/Editing.djot @@ -0,0 +1,181 @@ +{v-short="Editing"} +# editing this wiki + +This wiki follows proper wiki philosophy, meaning that ⓐ all content + is subject to change and deletion by members at any time, ⓑ it is + assumed that people will put the most time and effort into things + they are most passionate or knowledge·able about, ⓒ the + generally‐accepted _goal_ is in making the wiki _better_ or _more + interesting_ and not in being _right_ or _wrong_, and ⓓ the result + should be taken as a slightly‐inaccurate consensus opinion of the + current moment which captures nobody’s worldview correctly but + never·the·less is fun, useful, or meaningful to spend time with. +It should go without saying that nobody believes everything on this + site and everybody believes some of it. + +Be aware of the [][Meta:Licence] for this site; when you contribute, + you do so under these terms. + +Wiki editing is done using Git; the git repository is located at + `ssh://wiki@git.ladys.computer/srv/git/Wiki`. +Obviously, only people who have s·s·h keys registered with the `wiki` + user to be able to edit. +Registration is by invitation only. + +The file structure of the wiki is as follows :`⁠`{=html}— + +``` +Sources/ +↳ Category/ +↳ Editor/ +↳ Meta/ +↳ Namespace/ +↳ Page/ +↳ Special/ +``` + +The directories inside of `Sources/` are the wiki + [Namespaces][Special:Namespaces]; `Pages/` is the namespace for + ordinary pages. +Pages are written in [Djot][]{title="Djot (/dʒɑt/)"} with support for + the additional features documented below. + +Filenames… + +- *must not* include spaces. +- _should_ be PascalCase. +- _should_ closely match the title of the page (but _need not_ match it + exactly). + +They also need to end in the extension `.djot`. + +The first thing you should do is set up one or more [Editor][Editor:] + pages describing yoursel{f∣ves}. + +The website is rebuilt on every push; Git _should_ warn you if there + are any errors. +Contact me ([][@:Lady]{.sig}) if things go horribly wrong. + +{#djot-ext} +## extensions to the Djot syntax + +{id="djot.links-internal"} +### internal links + +A reference link which contains a colon is an internal link. +Typically, you should not include link text and just let it be + autogenerated from the page title. + +- For any page, its full reference is `[][NamespaceName:FileName]`. + +- Some namespaces have an abbreviated syntax :`⁠`{=html}— + + - Pages in the `Page` namespace can be referred to as just + `[][:FileName]`. + + - Namespaces themselves can be linked as `[][NamespaceName:]`; this + is short for `[][Namespace:NamespaceName]`. + *Namespace pages are not implemented yet.* + + - Editor pages can be linked as `[][@:YourName]`. + Add the class `sig` to format the link as a signature. + + - Category pages can be linked as `[][#:Category]`. *Category pages + are not implemented yet.* + +- The `v` attribute can be used to select an alternate title for the + page. + For example, `[][:FileName]{v=plural}`. + Variant titles must be specified on the title of the page being + linked, for example `{v-plural=FileNames}`. + +- To link a section within a page, follow its filename with a hash and + the section i·d: `[][:FileName#section]`. + *This isn’t implemented yet.* + +- If a page doesn’t exist, it will generate a “redlink” to + [][Special:NotFound] and the page will appear on the list at + [][Special:ToDo]. + *The latter isn’t implemented yet.* + +{id="djot.links-external"} +### external links + +For the most part these work exactly as expected. +Both reference links and inline links are allowed. + +You should give external links a `@title`, like + `{title="Some External Document"}`. +This is used to generate the title to use for the link in the listing + at the bottom of the page. +If the title matches the link text, you can leave the link text blank, + as in `[](https://example.com){title="Example Page"}`: + [](https://example.com){title="Example Page"}. + +{#bcp} +## best practices + +{id="bcp.writing" v-full="best practices while {writing ∣ editing}"} +### while {writing ∣ editing} + +- *Use Unicode* to the best of your ability. + You can escape special characters using the following + syntax :`⁠`{=html}— `` `&#xNN;`{=html}`` (where `NN` = the + codepoint in hexadecimal). + However, it is generally best to just input the characters directly + if you are able. + +- *Wrap lines* to (at most) 71 characters. + +- *Indent with spaces,* not tabs. + +- *Put each sentence on its own line.* + This helps to keep git diffs clean and means that only sentences, not + entire paragraphs, will need to be reflowed. + +- *Don’t capitalize titles,* unless they begin with a proper noun. + (*Do* capitalize filenames.) + +- *Sign opinions,* ideally with a link to your [Editor][Editor:]’s + page, like this: [][Editor:Lady]{.sig}. + This offers them some protection against other people removing them + just because they disagree. + +- *Communicate in‐band,* again with signatures; if you want to talk + about the contents of a page, there is no better place to do that + than the page itself. + +- *Feel free to copy·edit* other people’s words (including and up to + deleting and re·writing the whole thing), but *try to preserve + ideolect* (e·g don’t change someone else’s typography for no + reason). + +{id="bcp.git" v-full="best practices using git"} +### using git + +- *Use descriptive commit names.* + These don’t have to be long, but they should be informative enough + that someone following the [Atom feed][] has a general idea of + what the change entails. + +- *Rebase, don’t merge.* + We want to preserve a linear commit history. + You should probably set `git config --global pull.ff only` if you + haven’t already. + +- *Only force push [with lease][git push --force-with-lease].* + Ideally, don’t force push at all, but there are some cases where it + might be necessary (e·g, if you accidentally make a merge commit). + +- You can work on changes you don’t want to be live yet in a branch, + but *branching is discouraged* and it’s better to just work messily + on `live`. + +[Djot]: + https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/maste + r/doc/syntax.html +[Atom feed]: + https://git.ladys.computer/Wiki/atom +[git push --force-with-lease]: + https://git-scm.com/docs/git-push#Documentation/git-push.txt---no-for + ce-with-lease