Add more user-oriented documentation for the documentation system.
This commit is contained in:
parent
e3298c6320
commit
9934788155
|
@ -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>>!
|
||||
|
|
Loading…
Reference in New Issue
Block a user