mirror of
https://github.com/rkd77/elinks.git
synced 2024-09-06 23:44:43 -04:00
The AsciiDoc 7.1.2 configuration files included in the ELinks source tree apparently aren't compatible with AsciiDoc 8.4.4: [ASCIIDOC] doc/elinks.1.xml FAILED: [listdef-bulleted] missing section: [listtags-None] make[1]: *** [elinks.1.xml] Error 1 Fix this by including asciidoc.py from AsciiDoc 7.1.2 as well. The build system now doesn't care at all whether the user has installed some version of AsciiDoc or not.
165 lines
6.2 KiB
Plaintext
165 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:
|
|
|
|
- python: interpreter for asciidoc, which is 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.
|
|
|