doc/README

   1                         Overview of the ELinks documentation
   2
   3 There is only limited documentation available for ELinks so far, sorry. It
   4 basically consists of the documents in this directory and the features.conf,
   5 README and INSTALL files in the project's root directory.
   6
   7 You are encouraged to get a copy of the ELinks manual. It tries to be a
   8 complete book of all there is to know about ELinks. For example, most files
   9 listed in the next section is in some way part of the ELinks manual.
  10
  11 Instructions on building the manual is given below. If you do not intend to
  12 build it yourself either access it on the ELinks homepage or, if you
  13 downloaded ELinks via a tarball, the manual should be in the html/ directory.
  14
  15
  16 Where to start
  17 --------------
  18
  19 This sections tries to give a quick overview of important files you will find
  20 in this directory or it's children.
  21
  22  - Man pages:
  23
  24         elinks(1) ................................... man/man1/elinks.1
  25         elinks.conf(5) .............................. man/man5/elinks.conf.5
  26         elinkskeys(5) ............................... man/man5/elinkskeys.5
  27
  28    Man pages are best viewed with the man program. The easiest way to do this
  29    is by telling the man program to look for man pages in the doc/man
  30    directory by using the -M switch. If you are standing in the top-level
  31    directory, you can do this by invoking the man program using:
  32
  33         man -M doc/man elinks.conf
  34
  35  - User's Guide:
  36
  37         Getting ELinks up and running................ installation.txt
  38         Introduction to the World of ELinks ......... introduction.txt
  39         Frequently Asked Questions .................. faq.txt
  40         JavaScript/ECMAScript in ELinks ............. ecmascript.txt
  41         Notes on User Feedback ...................... feedback.txt
  42         The Smallest Binary Quest Spoilerbook ....... small.txt
  43
  44    Note: The ELinks manual really should be read in one of the generated
  45    formats: html, html-chunked or pdf, however the entry point can be found in
  46    manual.txt and might be of some help, when deciding what other .txt
  47    documents to read in this directory.
  48
  49  - Developer's Guide:
  50
  51         Introduction to ELinks Developing ........... dev-intro.txt
  52         The Demented Guide to Source Hacking ........ hacking.txt
  53
  54    The developing intro tries to explain some of the basic concepts in the
  55    ELinks internal. While the hacking guide contains great deal about general
  56    source code structure and especially guidelines regarding coding style,
  57    submitting patches etc., thus every aspiring developer should take the
  58    pains to read through it, do not forget to also look for README and similar
  59    text files in the subdirectories containing the relevant sources for
  60    detailed notes regarding given modules/subsystems. Additionally, it is
  61    possible to build API docs. More about this below.
  62
  63         The Lua Scripting Book ...................... lua-scripting.txt
  64         Events Reference Sheet ...................... events.txt
  65
  66    The above covers internal scripting, by which we mean scripting of the
  67    browser internals through embedded Lua, Guile or Perl scripts. ECMAScript
  68    scripts embedded in documents have nothing to do with that.
  69
  70
  71 Building documentation
  72 ----------------------
  73
  74 The following tools are used for generating documentation in various formats:
  75
  76  - python: interpreter for asciidoc, which is the basic tool for
  77    lifting the .txt files to other formats.
  78  - xmlto: used for outputting chunked HTML and man pages.
  79  - jw: used for pdf documents.
  80  - pod2html: used for perl docs.
  81
  82 All these tools are checked by configure, thus to successfully build all the
  83 possible documentation (with the tools available on the system), just run
  84
  85         $ make all-docs
  86
  87 in the doc/ directory. It will build, if possibly, the manual in the following
  88 manual formats (with tool requirements listed):
  89
  90  - HTML one-file (asciidoc)
  91  - HTML chunked / multiple files (asciidoc + xmlto)
  92  - PDF (asciidoc + jw)
  93
  94 and the following man page formats:
  95
  96  - HTML (asciidoc)
  97  - man / groff (asciidoc + xmlto)
  98
  99 Note: You do not need to build manpages. They are shipped with ELinks. However,
 100 if you want to have the manpages to match your local configuration and changes
 101 you can rebuild them (this is mostly an issue with elinks.conf(5) which might
 102 otherwise contain options that is not supported by the version you install.
 103
 104 Note: You must first build the ELinks binary for "make all-docs" to work
 105 successfully. The binary is used for getting option documentation.
 106
 107 The documentation can be installed with:
 108
 109         $ make install-doc
 110
 111 Building API documentation
 112 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 113
 114 There is some starting effort to make it possible to build HTML documentation
 115 of the APIs presented by the different modules and subsystems in ELinks. To
 116 build API documentation run:
 117
 118         $ make api
 119
 120 in the doc/ directory. The API documentation can then be found in the doc/api/
 121 directory.
 122
 123 NOTE: Currently only few files provides API docs and there is no over-all
 124 structure of the various APIs.
 125
 126 The API toolchain uses a Perl script (doc/tools/code2doc) to extract info from
 127 header files and generate text files with AsciiDoc markup. The text files are
 128 then converted to HTML with AsciiDoc.
 129
 130 To get an idea of how the code markup works take a look at src/dom/stack.h.
 131 It has a small tag saying that it provides API docs for the dom-stack module:
 132
 133         /* API Doc :: dom-stack */
 134
 135 The API doc markup should be pretty straight forward. Here is an example of the
 136 basic structure:
 137
 138         /** <title>
 139          *
 140          * <content>
 141          */
 142
 143 Only text in comments starting with '/**' are used. If the comment immediately
 144 preceeds a declaration of some struct, enum, typedef, function, or macro, the
 145 name of the declared identifier will be used when creating the output to create
 146 anchors which can be referred to using ref:[].
 147
 148
 149 Contributing
 150 ------------
 151
 152 Contributions are very warmly welcomed, whether it is fixing typos or bad
 153 grammar, rewritings or new material. Any information relevant to ELinks usage
 154 can be included in the manual, including FAQ material, tips and cheats ;)
 155
 156 There is no strict codingstyle, but please don't limit your use of whitespaces
 157 and take a look at the style used in the current documents to get ideas of what
 158 is reasonable.
 159
 160 Contributions should be sent to Jonas Fonseca <fonseca@diku.dk> or to the
 161 ELinks mailing list. If you are changing something in an existing document,
 162 please read about how to make unified patches in the Patches section of the
 163 doc/hacking.txt file.
 164