Lady’s Gitweb - Wiki/blob - 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 emphasized text to change what
 119     H·T·M·L element is used.
 120   The following values are supported:8--:
 121
 122   - `_b_{as=b}`
 123   - `_cite_{as=cite}`
 124   - `_i_{as=i}`
 125   - `_u_{as=u}`
 126
 127 - There are symbols defined for spaces, invisible characters, and a
 128     couple of other conveniences.
 129   You can view the full list [here][GitWikiWeb/config.yaml].
 130   You can also escape any special character using the following
 131     syntax:8--: `:U+####:` (where `####`:mathsp:=:mathsp:the
 132     codepoint in hexadecimal).
 133
 134 {#bcp}
 135 ## best practices
 136
 137 {id="bcp.writing" v-full="best practices while {writing ∣ editing}"}
 138 ### while {writing ∣ editing}
 139
 140 - *Use Unicode* to the best of your ability.
 141
 142 - *Wrap lines* to (at most) 71 characters.
 143
 144 - *Indent with spaces,* not tabs.
 145
 146 - *Put each sentence on its own line.*
 147   This helps to keep git diffs clean and means that only sentences, not
 148     entire paragraphs, will need to be reflowed.
 149
 150 - *Don’t capitalize titles,* unless they begin with a proper noun.
 151   (*Do* capitalize filenames.)
 152
 153 - *Sign opinions,* ideally with a link to your [Editor][Editor:]’s
 154     page, like this: [][Editor:Lady]{.sig}.
 155   This offers them some protection against other people removing them
 156     just because they disagree.
 157
 158 - *Communicate in‐band,* again with signatures; if you want to talk
 159     about the contents of a page, there is no better place to do that
 160     than the page itself.
 161
 162 - *Feel free to copy·edit* other people’s words (including and up to
 163     deleting and re·writing the whole thing), but *try to preserve
 164     ideolect* (e·g don’t change someone else’s typography for no
 165     reason).
 166
 167 {id="bcp.git" v-full="best practices using git"}
 168 ### using git
 169
 170 - *Use descriptive commit names.*
 171   These don’t have to be long, but they should be informative enough
 172     that someone following the [Atom feed][] has a general idea of
 173     what the change entails.
 174
 175 - *Rebase, don’t merge.*
 176   We want to preserve a linear commit history.
 177   You should probably set `git config --global pull.ff only` if you
 178     haven’t already.
 179
 180 - *Only force push [with lease][git push --force-with-lease].*
 181   Ideally, don’t force push at all, but there are some cases where it
 182     might be necessary (e·g, if you accidentally make a merge commit).
 183
 184 - You can work on changes you don’t want to be live yet in a branch,
 185     but *branching is discouraged* and it’s better to just work messily
 186     on `live`.
 187
 188 [Atom feed]:
 189   https://git.ladys.computer/Wiki/atom
 190 [Djot]:
 191   https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/maste
 192   r/doc/syntax.html
 193 [GitWikiWeb/config.yaml]:
 194   https://git.ladys.computer/GitWikiWeb/blob/refs/heads/ladys:/config.y
 195   aml
 196 [git push --force-with-lease]:
 197   https://git-scm.com/docs/git-push#Documentation/git-push.txt---no-for
 198   ce-with-lease