Add more user-oriented documentation for the documentation system.

This commit is contained in:
Tim Allen 2020-09-03 16:49:18 +10:00
parent e3298c6320
commit 9934788155

View File

@ -1,11 +1,26 @@
= Kakoune's online documentation
This is Kakoune's online documentation system.
== Using the documentation browser
Documentation buffers are like any other buffer, so you can scroll through them
as normal, search within a topic with `/`, etc. However, they can also contain
links, <<doc#demonstration-target,like this>>. When you see a link, you can
follow it by moving the cursor onto it and pressing Enter. If the link takes you
to a different documentation topic, you can get back by using the `:buffer`
command.
== Commands
*doc* <topic>::
*doc* <topic> [<target>]::
*alias* help +
display documentation about a topic. The completion list displays the
available topics
This command displays documentation about the named topic in a new buffer.
If a target is supplied, Kakoune will automatically jump to that target
when the buffer is opened.
+
For a list of available topics, or available targets within a topic, check
the completion menu that appears when typing the command at the prompt.
== Options
@ -13,3 +28,31 @@
If set, the `:doc` command will try to display documentation in the Kakoune
client with this name.
See <<commands#clients-and-sessions,`:doc commands clients-and-sessions`>>
== Writing documentation
Documentation must be in AsciiDoc format, with the extension `.asciidoc`,
and stored somewhere within <<doc#sources,the documentation search path>>.
Kakoune's built-in documentation renderer does not necessarily support every
feature, so don't go overboard with formatting.
To create a link to another documentation topic, the URL should be the topic-
name, just like <<doc#commands,`:doc`>> uses. Because topics are identified
only by their basename, you should take care that your topic's name does not
collide with any of the names used by other plugins or Kakoune's standard
library.
== Sources
The <<doc#commands,`:doc` command>> searches within the following locations for
documents in the AsciiDoc format (`*.asciidoc`):
* The user plugin directory, `"%val{config}/autoload"`
* The system documentation directory, `"%val{runtime}/doc"`
* The system plugin directory, `"%val{runtime}/rc"`
It searches recursively, and follows symlinks.
== Demonstration target
Well done! You can <<doc#using-the-documentation-browser,go back now>>!