mirror of
https://github.com/rkd77/elinks.git
synced 2024-08-21 21:04:38 -04:00
164 lines
6.2 KiB
Plaintext
164 lines
6.2 KiB
Plaintext
Overview of the ELinks documentation
|
|
|
|
There is only limited documentation available for ELinks so far, sorry. It
|
|
basically consists of the documents in this directory and the features.conf,
|
|
README and INSTALL files in the project's root directory.
|
|
|
|
You are encouraged to get a copy of the ELinks manual. It tries to be a
|
|
complete book of all there is to know about ELinks. For example, most files
|
|
listed in the next section is in some way part of the ELinks manual.
|
|
|
|
Instructions on building the manual is given below. If you do not intend to
|
|
build it yourself either access it on the ELinks homepage or, if you
|
|
downloaded ELinks via a tarball, the manual should be in the html/ directory.
|
|
|
|
|
|
Where to start
|
|
--------------
|
|
|
|
This sections tries to give a quick overview of important files you will find
|
|
in this directory or it's children.
|
|
|
|
- Man pages:
|
|
|
|
elinks(1) ................................... man/man1/elinks.1
|
|
elinks.conf(5) .............................. man/man5/elinks.conf.5
|
|
elinkskeys(5) ............................... man/man5/elinkskeys.5
|
|
|
|
Man pages are best viewed with the man program. The easiest way to do this
|
|
is by telling the man program to look for man pages in the doc/man
|
|
directory by using the -M switch. If you are standing in the top-level
|
|
directory, you can do this by invoking the man program using:
|
|
|
|
man -M doc/man elinks.conf
|
|
|
|
- User's Guide:
|
|
|
|
Getting ELinks up and running................ installation.txt
|
|
Introduction to the World of ELinks ......... introduction.txt
|
|
Frequently Asked Questions .................. faq.txt
|
|
JavaScript/ECMAScript in ELinks ............. ecmascript.txt
|
|
Notes on User Feedback ...................... feedback.txt
|
|
The Smallest Binary Quest Spoilerbook ....... small.txt
|
|
|
|
Note: The ELinks manual really should be read in one of the generated
|
|
formats: html, html-chunked or pdf, however the entry point can be found in
|
|
manual.txt and might be of some help, when deciding what other .txt
|
|
documents to read in this directory.
|
|
|
|
- Developer's Guide:
|
|
|
|
Introduction to ELinks Developing ........... dev-intro.txt
|
|
The Demented Guide to Source Hacking ........ hacking.txt
|
|
|
|
The developing intro tries to explain some of the basic concepts in the
|
|
ELinks internal. While the hacking guide contains great deal about general
|
|
source code structure and especially guidelines regarding coding style,
|
|
submitting patches etc., thus every aspiring developer should take the
|
|
pains to read through it, do not forget to also look for README and similar
|
|
text files in the subdirectories containing the relevant sources for
|
|
detailed notes regarding given modules/subsystems. Additionally, it is
|
|
possible to build API docs. More about this below.
|
|
|
|
The Lua Scripting Book ...................... lua-scripting.txt
|
|
Events Reference Sheet ...................... events.txt
|
|
|
|
The above covers internal scripting, by which we mean scripting of the
|
|
browser internals through embedded Lua, Guile or Perl scripts. ECMAScript
|
|
scripts embedded in documents have nothing to do with that.
|
|
|
|
|
|
Building documentation
|
|
----------------------
|
|
|
|
The following tools are used for generating documentation in various formats:
|
|
|
|
- asciidoc: the basic tool for lifting the .txt files to other formats.
|
|
- xmlto: used for outputting chunked HTML and man pages.
|
|
- jw: used for pdf documents.
|
|
- pod2html: used for perl docs.
|
|
|
|
All these tools are checked by configure, thus to successfully build all the
|
|
possible documentation (with the tools available on the system), just run
|
|
|
|
$ make all-docs
|
|
|
|
in the doc/ directory. It will build, if possibly, the manual in the following
|
|
manual formats (with tool requirements listed):
|
|
|
|
- HTML one-file (asciidoc)
|
|
- HTML chunked / multiple files (asciidoc + xmlto)
|
|
- PDF (asciidoc + jw)
|
|
|
|
and the following man page formats:
|
|
|
|
- HTML (asciidoc)
|
|
- man / groff (asciidoc + xmlto)
|
|
|
|
Note: You do not need to build manpages. They are shipped with ELinks. However,
|
|
if you want to have the manpages to match your local configuration and changes
|
|
you can rebuild them (this is mostly an issue with elinks.conf(5) which might
|
|
otherwise contain options that is not supported by the version you install.
|
|
|
|
Note: You must first build the ELinks binary for "make all-docs" to work
|
|
successfully. The binary is used for getting option documentation.
|
|
|
|
The documentation can be installed with:
|
|
|
|
$ make install-doc
|
|
|
|
Building API documentation
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
There is some starting effort to make it possible to build HTML documentation
|
|
of the APIs presented by the different modules and subsystems in ELinks. To
|
|
build API documentation run:
|
|
|
|
$ make api
|
|
|
|
in the doc/ directory. The API documentation can then be found in the doc/api/
|
|
directory.
|
|
|
|
NOTE: Currently only few files provides API docs and there is no over-all
|
|
structure of the various APIs.
|
|
|
|
The API toolchain uses a Perl script (doc/tools/code2doc) to extract info from
|
|
header files and generate text files with AsciiDoc markup. The text files are
|
|
then converted to HTML with AsciiDoc.
|
|
|
|
To get an idea of how the code markup works take a look at src/dom/stack.h.
|
|
It has a small tag saying that it provides API docs for the dom-stack module:
|
|
|
|
/* API Doc :: dom-stack */
|
|
|
|
The API doc markup should be pretty straight forward. Here is an example of the
|
|
basic structure:
|
|
|
|
/** <title>
|
|
*
|
|
* <content>
|
|
*/
|
|
|
|
Only text in comments starting with '/**' are used. If the comment immediately
|
|
preceeds a declaration of some struct, enum, typedef, function, or macro, the
|
|
name of the declared identifier will be used when creating the output to create
|
|
anchors which can be referred to using ref:[].
|
|
|
|
|
|
Contributing
|
|
------------
|
|
|
|
Contributions are very warmly welcomed, whether it is fixing typos or bad
|
|
grammar, rewritings or new material. Any information relevant to ELinks usage
|
|
can be included in the manual, including FAQ material, tips and cheats ;)
|
|
|
|
There is no strict codingstyle, but please don't limit your use of whitespaces
|
|
and take a look at the style used in the current documents to get ideas of what
|
|
is reasonable.
|
|
|
|
Contributions should be sent to Jonas Fonseca <fonseca@diku.dk> or to the
|
|
ELinks mailing list. If you are changing something in an existing document,
|
|
please read about how to make unified patches in the Patches section of the
|
|
doc/hacking.txt file.
|
|
|