kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

doc.asciidoc (1852B)


      1 = Kakoune's online documentation
      2 
      3 This is Kakoune's online documentation system.
      4 
      5 To see what documentation topics are available, type `:doc` and look at the
      6 completion menu.  To view a particular topic, type its name or select it
      7 from the completion menu.  Then hit Enter.
      8 
      9 Documentation will be displayed in the client named in the `docsclient` option.
     10 
     11 == Using the documentation browser
     12 
     13 Documentation buffers are like any other buffer, so you can scroll through
     14 them as normal, search within a topic with `/`, etc.  However, they can also
     15 contain links: <<doc#demonstration-target,like this>>.  Links can be followed
     16 by moving the cursor onto them and pressing Enter.  If a link takes you to
     17 a different documentation topic, you can return to the original by using the
     18 `:buffer` command.
     19 
     20 == Writing documentation
     21 
     22 Documentation must be in AsciiDoc format, with the extension `.asciidoc`.
     23 It must be stored somewhere within <<doc#sources,the documentation search
     24 path>>.  Kakoune's built-in documentation renderer does not necessarily
     25 support every feature, so don't go overboard with formatting.
     26 
     27 To create a link to another documentation topic, the URL should be the topic's
     28 name, just like `:doc` uses.  Because topics are identified only by their
     29 basename, you should take care that your topic's name does not conflict with
     30 any of the names used either by other plugins or by Kakoune's standard library.
     31 
     32 == Sources
     33 
     34 The `:doc` command searches within the following locations for
     35 documents in the AsciiDoc format (`*.asciidoc`):
     36 
     37 * The user plugin directory, `"%val{config}/autoload"`
     38 * The system documentation directory, `"%val{runtime}/doc"`
     39 * The system plugin directory, `"%val{runtime}/rc"`
     40 
     41 It searches recursively, and follows symlinks.
     42 
     43 == Demonstration target
     44 
     45 Well done! You can <<doc#using-the-documentation-browser,go back now>>!