HelpOnGithubWiki - coq/coq GitHub Wiki
Help on Cocorico!, the Coq Wiki on Github
Some advice about the current wiki, mainly for wiki editors.
Syntax
Note: Please always use the Github flavored markdown syntax
when editing this wiki. Truly, Github Wiki allows to choose different
formats for each page, but let's keep this wiki uniform, for editors
and administrators sanity. That's the default when editing a page through
the Github web interface (after clicking on the Edit
or New page
buttons),
so please leave it this way.
- Tutorial on Github markdown syntax : https://guides.github.com/features/mastering-markdown/
- Full spec of Github markdown : https://github.github.com/gfm/
Before creating a new page ...
Before creating a new page, please use first the search tool
(the find a page...
form in the right sidebar) to check whether
there already exists a page similar to what you intend to create.
Indeed, with this wiki, there's no warning when the name of the new page is close to something that already exists. In particular, be careful with misspelling of page names.
History
-
The global history of the whole Cocorico wiki is here: Github history. Note that old revisions of pages may still be in MoinMoin syntax.
-
For a specific page, the mention
<n> revisions
just below the title is a link leading to the history of this page. Or you can add/_history
to the page URL to get there. When on the history page, you can select two revisions and click onCompare Revisions
to get a diff.
Git
As mentioned at the bottom of the right sidebar, it is possible to
clone this wiki locally
, as a git repository:
git clone https://github.com/coq/coq.wiki.git
Or for registered Github users:
git clone [email protected]:coq/coq.wiki.git
A wiki page named FooBar
will correspond to a file named FooBar.md
in this
repository (md
stands for markdown
, the name of the syntax format).
The main page is Home.md. Images and attachments are in the files
subdirectories.
This may indeed be a convenient way to browse the wiki files locally, inspect their history, etc. You may even use this to push modifications to the wiki if you have write access to the Coq repository on Github. In this case, please never push modifications forcingly, only fast-forward ones. Forced modifications will be undone by administrators as soon as they are noticed.
For large-scale modifications and/or additions of images and attachments, one may propose a pull request with respect to this git mirror of the Wiki.
Subdirectories
You may have noticed that all existing pages appear to be at toplevel:
the full URL of the page FooBar
is https://github.com/coq/coq/wiki/FooBar
,
and there's never anything between wiki
and FooBar
.
Actually, when accessing this wiki via its git repository (see above), some files don't live at toplevel, but in various subdirectories. But these subdirectories aren't reflected in the URL proposed by Github Wiki. That's a bit awkward, but well, so be it.
As a consequence, please use unambiguous file names, even if you regroup
these pages in some subdirectories via the git interface. We suggest using
the dash -
to prefix page names with what would normally be a directory
part. See for instance the various Tactic-xyz
pages, that are actually
placed in the Tactics
subdirectory.
Note that there's two situations where the subdirectory part of a filename is visible in the final URL: images and attached files (e.g. pdf), see below.
Images and attachments
Note: the Github web interface for editing pages could only insert images that are stored elsewhere (or already present beforehand in our Wiki). Same for links to attachment files. For uploading images and non-markdown files in this Wiki, you must access this wiki through git, see above, and submit a pull request if you do not have write access.
For images, the markdown syntax is ![textual description](files/image_name.png)
.
See page HandMul for an example of wiki page with some images.
For now, all these images are in the files
subdirectory of the git
repository, please keep it this way.
For attachment files (for instance pdf
), simply put a local link,
whose markdown syntax is something like [textual description](files/attachment_filename.pdf)
.
See pages CoqIW2017 and UTF8Module for live examples of pages with attachments.
Here again, these attachment files are all in the files
subdirectory of the
git repository of this wiki, please keep it this way.
For attachments of code (Coq scripts, OCaml files, etc), note that you could simply use the Gist feature of Github, and hence avoid uploading this code file to the Wiki itself.
Compared with the earlier MoinMoin wiki...
-
Apparently no features such as MoinMoin's
#include
or#redirect
or<<TableOfContents>>
. For redirections, you could use a symbolic link through git. -
All pages are public, no ACL to restrict access to some happy few.
-
The CamlCase words aren't automatically considered as links in Github. It's up to you to turn them into links via the
[CamlCase](CamlCase)
syntax. -
In markdown, tables should have a header row, unlike in MoinMoin syntax. See for instance FormalizedAndVerified for an example of table.
-
The page style of Github makes it difficult to create hugely large tables, so for instance Top100MathematicalTheoremsInCoq has now many sections instead of a big table.