diff --git a/doc/.gitignore b/doc/.gitignore index 44553d963..af1b7aec2 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,5 +1,14 @@ -html -pdf -txt -web *.tmp +*.html +*.pdf +*.xml +*.1 +*.5 +api +web +features.txt +keymap-actions.txt +keymap-defaults.txt +manual.html-chunked +option-command.txt +option-config.txt diff --git a/doc/Makefile b/doc/Makefile index ea18c3fc9..b66c37c64 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -3,66 +3,31 @@ include $(top_builddir)/Makefile.config SUBDIRS = man -HTML_DIR = $(DESTDIR)html -MAN_DIR = $(DESTDIR)man -PDF_DIR = $(DESTDIR)pdf -XML_DIR = $(DESTDIR)xml +# A little trick to simplify some of the rules. +VPATH = $(builddir):$(srcdir):$(top_srcdir)/contrib/perl -# Keep generated .txt files relative to the source directory -# and files they are included in. -TXT_DIR = $(top_srcdir)/doc/txt +docdir = $(datadir)/doc -DOC_DIRS = \ - $(HTML_DIR) \ - $(MAN_DIR)/man1 \ - $(MAN_DIR)/man5 \ - $(TXT_DIR) \ - $(XML_DIR) +# Used by install-doc +HTML_DIR = $(DESTDIR)$(docdir)/$(PACKAGE)/html +PDF_DIR = $(DESTDIR)$(docdir)/$(PACKAGE)/pdf -# TODO: perl.pod should be pod2ized during make install. --pasky +ASCIIDOC_CONF = $(srcdir)asciidoc.conf +ASCIIDOC_FLAGS += -f $(ASCIIDOC_CONF) -a "builddir=$(CURDIR)/" -# XXX: manual.txt is the master document and must be first. -MANUAL_FILES = \ - manual.txt \ - \ - bookmarks.txt \ - ecmascript.txt \ - exmode.txt \ - faq.txt \ - installation.txt \ - introduction.txt \ - lua-scripting.txt \ - mailcap.txt \ - marks.txt \ - mime.txt \ - remote.txt \ - small.txt \ - tabs.txt \ - terminals.txt \ - urlshortcuts.txt +############################################################################# +# Build files -### Script Dependencies -# - -ELINKS = $(top_builddir)/src/elinks -KBDBIND = $(top_srcdir)/src/config/kbdbind.c -FEATURES = $(top_srcdir)/features.conf - -### Locale env vars to override system one to ensure commands -# using elinks binary will generate texts in english -# -LOCALES = LC_ALL=C LANGUAGE=en - -### Scripts -# - -HELP2DOC = $(top_srcdir)/doc/tools/help2doc -IMPORT_FEATURES_CONF = $(top_srcdir)/doc/tools/import-features.conf -MAKE_ELINKS_MANPAGE = $(top_srcdir)/doc/tools/make-elinks-manpage -MAKE_ELINKSKEYS_MANPAGE = $(top_srcdir)/doc/tools/make-elinkskeys-manpage +TXT_DOCS = \ + features.txt \ + keymap-actions.txt \ + keymap-defaults.txt \ + option-command.txt \ + option-config.txt HTML_DOCS-$(CONFIG_ASCIIDOC) += \ elinks.1.html \ + elinks.conf.5.html \ elinkskeys.5.html \ hacking.html \ manual.html @@ -75,103 +40,156 @@ HTML_DOCS-$(CONFIG_POD2HTML) += \ perl-hooks.html MAN_DOCS-$(CONFIG_XMLTO) += \ - man1/elinks.1.in \ - man5/elinkskeys.5 + elinks.1 \ + elinks.conf.5 \ + elinkskeys.5 -# Only jw is used for generating PDF. +# Use jw for generating PDF, since xmlto seems to freak out. PDF_DOCS-$(CONFIG_JW) += \ manual.pdf -MAN_DOCS += man5/elinks.conf.5 -MAN_DOCS += $(MAN_DOCS-yes) -HTML_DOCS += $(HTML_DOCS-yes) -PDF_DOCS += $(PDF_DOCS-yes) +############################################################################# +## Set the default doc rules -man-docs: doc-dirs $(addprefix $(MAN_DIR)/,$(MAN_DOCS)) -html-docs: doc-dirs $(addprefix $(HTML_DIR)/,$(HTML_DOCS)) -pdf-docs: doc-dirs $(addprefix $(PDF_DIR)/,$(PDF_DOCS)) +MAN_DOCS = $(MAN_DOCS-yes) +HTML_DOCS = $(HTML_DOCS-yes) +PDF_DOCS = $(PDF_DOCS-yes) -all-docs: man-docs html-docs pdf-docs +txt: $(TXT_DOCS) +html: txt $(HTML_DOCS) +pdf: txt $(PDF_DOCS) +man: txt $(MAN_DOCS) -### Build Rules -# +all-docs: man html pdf -doc-dirs: - $(INSTALL) -d $(DOC_DIRS) +install-doc: all-docs update-man install + @$(foreach doc,$(HTML_DOCS), \ + if test -d $(doc); then \ + $(MKINSTALLDIRS) $(DESTDIR)$(docdir)/$(PACKAGE)/html/$(doc); \ + $(call ncmd,installdata,$(doc)/*,$(HTML_DIR)/$(doc)); \ + else \ + $(MKINSTALLDIRS) $(DESTDIR)$(docdir)/$(PACKAGE)/html; \ + $(call ncmd,installdata,$(doc),$(HTML_DIR)); \ + fi;) + @$(foreach doc,$(PDF_DOCS), \ + $(MKINSTALLDIRS) $(DESTDIR)$(docdir)/$(PACKAGE)/pdf; \ + $(call ncmd,installdata,$(doc),$(PDF_DIR);)) + +update-man: man + @$(if $(MAN_DOCS), \ + $(call ncmd,installdata,elinks.1,man/man1/elinks.1.in); \ + $(call ncmd,installdata,elinkskeys.5,man/man5/); \ + $(call ncmd,installdata,elinks.conf.5,man/man5/)) -# $(MAN_DIR) intentionally left out clean-local: - @$(RM) -r $(HTML_DIR) $(XML_DIR) $(TXT_DIR) $(PDF_DIR) *.tmp + @$(RM) -r $(TXT_DOCS) $(MAN_DOCS) $(HTML_DOCS) $(PDF_DOCS) *.tmp *.xml + +# TODO: perl.pod should be pod2ized during make install. --pasky +install-local: -# Autogenerated asciidoc files. +############################################################################# +# Generated asciidoc files -$(TXT_DIR)/import-features.conf.txt: $(FEATURES) $(IMPORT_FEATURES_CONF) - $(IMPORT_FEATURES_CONF) > $@ +# Scripts and Dependencies +HELP2DOC = $(srcdir)tools/help2doc +CONF2DOC = $(srcdir)tools/conf2doc +KEYS2DOC = $(srcdir)tools/keys2doc +ELINKS = $(top_builddir)/src/elinks +FEATURES = $(top_srcdir)/features.conf +KBDBIND = $(top_srcdir)/src/config/kbdbind.c -$(TXT_DIR)/elinks.1.%.txt: $(MAKE_ELINKS_MANPAGE) $(ELINKS) $(HELP2DOC) Makefile - $(LOCALES) $(MAKE_ELINKS_MANPAGE) $@ $(ELINKS) $(HELP2DOC) > $@ +# Locale env vars to override system one to ensure commands +# using elinks binary will generate texts in english +LOCALES = LC_ALL=C LANGUAGE=en -$(TXT_DIR)/elinkskeys.5.%.txt: $(MAKE_ELINKSKEYS_MANPAGE) $(KBDBIND) Makefile - $(LOCALES) $(MAKE_ELINKSKEYS_MANPAGE) $@ $(KBDBIND) > $@ +# FIXME: Keep generated .txt files relative to the source directory and files +# they are included in. +quiet_cmd_help2doc = ' [$(LINK_COLOR)HELP2DOC$(END_COLOR)] $(RELPATH)$@' + cmd_help2doc = $(LOCALES) $(HELP2DOC) $(ELINKS) $@ > $@ + +quiet_cmd_conf2doc = ' [$(LINK_COLOR)CONF2DOC$(END_COLOR)] $(RELPATH)$@' + cmd_conf2doc = $(LOCALES) $(CONF2DOC) $(FEATURES) > $@ + +quiet_cmd_keys2doc = ' [$(LINK_COLOR)KEYS2DOC$(END_COLOR)] $(RELPATH)$@' + cmd_keys2doc = $(LOCALES) $(KEYS2DOC) $(KBDBIND) $@ > $@ + +quiet_cmd_code2doc = ' [$(LINK_COLOR)CODE2DOC$(END_COLOR)] $(RELPATH)$@' + cmd_code2doc = $(LOCALES) $(CODE2DOC) $< > $@ + +features.txt: $(FEATURES) $(CONF2DOC) + $(call cmd,conf2doc) + +keymap-%.txt: $(KBDBIND) $(KEYS2DOC) + $(call cmd,keys2doc) + +option-%.txt: $(ELINKS) $(HELP2DOC) + $(call cmd,help2doc) -# Man Pages +############################################################################# +# Build commands and macros -$(XML_DIR)/%.man.xml: $(TXT_DIR)/%.man.txt - $(ASCIIDOC) -b docbook -d manpage -o $@ $< + quiet_cmd_jw = ' [$(LINK_COLOR)JW$(END_COLOR)] $(RELPATH)$@' + cmd_jw = $(JW) -b $(2) $< -$(MAN_DIR)/man1/elinks.1.in: $(XML_DIR)/elinks.1.man.xml - $(XMLTO) -o $(MAN_DIR)/man1 man $< - sed 's/^\.TH "ELINKS" 1 .*/.TH "ELINKS" 1 "The ELinks text-browser" "$(shell date -I)" "The ELinks text-browser"/' \ - < $(MAN_DIR)/man1/elinks.1 > $@ - rm $(MAN_DIR)/man1/elinks.1 + quiet_cmd_xmlto = ' [$(LINK_COLOR)XMLTO$(END_COLOR)] $(RELPATH)$@' + cmd_xmlto = $(XMLTO) -o $(call outdir) $(3) $(2) $< -$(MAN_DIR)/man5/elinkskeys.5: $(XML_DIR)/elinkskeys.5.man.xml - $(XMLTO) -o $(MAN_DIR)/man5 man $< - sed -e 's/\\fI\\fR'\''/\\fI\\'\''\\fR/' < $@ > $@.tmp - sed 's/^\.TH "ELINKSKEYS" 5 .*/.TH "ELINKSKEYS" 5 "ELinks keybindings" "$(shell date -I)" "ELinks keybindings"/' \ - < $@.tmp > $@ - rm $@.tmp +quiet_cmd_pod2html = ' [$(LINK_COLOR)POD2HTML$(END_COLOR)] $(RELPATH)$@' + cmd_pod2html = $(POD2HTML) --outfile=$@ < $< -$(MAN_DIR)/man5/elinks.conf.5: $(ELINKS) $(HELP2DOC) Makefile - $(LOCALES) $(HELP2DOC) --elinks=$(ELINKS) --elinksconf > $@ +quiet_cmd_asciidoc = ' [$(LINK_COLOR)ASCIIDOC$(END_COLOR)] $(RELPATH)$@' + cmd_asciidoc = $(ASCIIDOC) $(ASCIIDOC_FLAGS) -b $(call backend) -d $(call doctype) -o $@ $< -# XHTML/CSS Man Pages +# Based on $@ find out asciidoc doctype or backend + xmlto output dir. +doctype = $(if $(findstring .1.,$@)$(findstring .5.,$@),manpage,book) +backend = $(if $(findstring .xml,$@),docbook,xhtml11) +outdir = $(if $(findstring -chunked,$@),$@,.) -$(HTML_DIR)/%.html: $(TXT_DIR)/%.html.txt - $(ASCIIDOC) -b xhtml11 -d manpage -o $@ $< +# Loosely track dependencies via asciidoc includes. +asciidoc_dep = sed -n 's/[{]builddir}//g;s@include::\(.*\)\[.*@$@: $< \1@p' < $< > .deps/$(@F).asciidoc -# The Manual +-include .deps/*.asciidoc -MANUAL_EXTRA_FILES = \ - $(TXT_DIR)/import-features.conf.txt \ - $(TXT_DIR)/elinks.1.html.txt \ - $(TXT_DIR)/elinkskeys.5.html.txt +# Do a little post-processing of man pages. Inserting title headers and date. +MAN_DATE = $(shell date -I) +man_desc = `sed -n 's/:Description:\s*\(.*\)/\1/p' < $(srcdir)$(subst .xml,.txt,$( $@.tmp && mv $@.tmp $@ -$(HTML_DIR)/manual.html: $(MANUAL_FILES) $(MANUAL_EXTRA_FILES) - $(ASCIIDOC) -b xhtml11 -d book -o $@ -n $< -$(HTML_DIR)/hacking.html: $(top_srcdir)/doc/hacking.txt - $(ASCIIDOC) -b xhtml11 -d book -o $@ -n $< +############################################################################# +# Build recipies -$(HTML_DIR)/dev-intro.html: $(top_srcdir)/doc/dev-intro.txt - $(ASCIIDOC) -b xhtml11 -d book -o $@ -n $< +%.html: %.txt $(ASCIIDOC_CONF) + $(call cmd,asciidoc,xhtml11) + @-$(call asciidoc_dep) -$(XML_DIR)/manual.xml: $(MANUAL_FILES) $(MANUAL_EXTRA_FILES) - $(ASCIIDOC) -b docbook -d book -o $@ $< +%.xml: %.txt $(ASCIIDOC_CONF) + $(call cmd,asciidoc,docbook) + @-$(call asciidoc_dep) -$(HTML_DIR)/manual.html-chunked: $(XML_DIR)/manual.xml - $(XMLTO) -o $@ html $< +%.1: %.1.xml + $(call cmd,xmlto,man) + @$(call man_hack,$(call man_desc)) -$(PDF_DIR)/manual.pdf: $(XML_DIR)/manual.xml - $(JW) -o $(PDF_DIR) -b pdf $< +%.5: %.5.xml + $(call cmd,xmlto,man) + @$(call man_hack,$(call man_desc)) -$(HTML_DIR)/perl.html: $(top_srcdir)/doc/perl.pod - $(POD2HTML) --outfile=$@ < $< +%.html-chunked: %.xml + $(call cmd,xmlto,html) + +%.pdf: %.xml + $(call cmd,jw,pdf) + +%.html: %.pod + $(call cmd,pod2html) + +perl-%.html: %.pl + $(call cmd,pod2html) -$(HTML_DIR)/perl-hooks.html: $(top_srcdir)/contrib/perl/hooks.pl - $(POD2HTML) --outfile=$@ < $< include $(top_srcdir)/Makefile.lib diff --git a/doc/README b/doc/README index be56d7f9b..375873080 100644 --- a/doc/README +++ b/doc/README @@ -57,7 +57,8 @@ in this directory or it's children. 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. + 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 @@ -94,11 +95,18 @@ 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. +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 + Contributing ------------ diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf new file mode 100644 index 000000000..ac0afaeb5 --- /dev/null +++ b/doc/asciidoc.conf @@ -0,0 +1,92 @@ +# AsciiDoc configuration file +# Copyright (c) Jonas Fonseca , 2006 + +# This file sets the following ELinks specific AsciiDoc macros: +# +# General purpose: +# - man:page[section]: which is used for linking between ELinks manpages. +# +# API Doc: +# - id:[] +# - enum:[] +# - func:[] +# - struct:[] +# - macro:[] +# - typedef:[] +# - ref:[] + +[replacements] +(^|[^-])--($|[^-])=\1--\2 + +# Some macros can have optional {0} value, that is what +# the {0%...} and {0#...} handles. + +############################################################################# +# DocBook + +ifdef::backend-docbook[] + +# To be replaced later +[attributes] +squote=@squote@ + +# No interlinking between elinks manpages +[man-inlinemacro] +{0%{target}} +{0#} +{0#{target}{0}} +{0#} + +# For manpages use less verbose linking +ifdef::doctype-manpage[] +[link-inlinemacro] +{0%<{target}>} +{0#{0} <{target}>} + +[http-inlinemacro] +{0%<http:{target}>} +{0#{0} <http:{target}>} + +[mailto-inlinemacro] +<{target}> + +endif::doctype-manpage[] +endif::backend-docbook[] + +############################################################################# +# XHTML11 + +ifdef::backend-xhtml11[] + +[attributes] +squote=' + +# Use the man:[] macro to link between elinks manpages +[man-inlinemacro] +{eval:re.match("elinks", "{target}") != None}{target}({0}) +{eval:re.match("elinks", "{target}") == None}{target}({0}) + +# API Doc macros + +[id-inlinemacro] +{0} + +[enum-inlinemacro] +enum {target}: {0} + +[func-inlinemacro] +{target}(): {0} + +[struct-inlinemacro] +struct {target}: {0} + +[macro-inlinemacro] +struct {target}: {0} + +[typedef-inlinemacro] +typedef {target}: {0} + +[ref-inlinemacro] +{0} + +endif::backend-xhtml11[] diff --git a/doc/elinks.1.txt b/doc/elinks.1.txt new file mode 100644 index 000000000..060336f69 --- /dev/null +++ b/doc/elinks.1.txt @@ -0,0 +1,175 @@ +elinks(1) +========= +:Description: The Elinks text-browser + +NAME +---- +elinks - lynx-like alternative character mode WWW browser + +SYNOPSIS +-------- +'elinks' [OPTION]... [URL]... + +DESCRIPTION +----------- + +'ELinks' is a text mode WWW browser, supporting colors, table rendering, +background downloading, menu driven configuration interface, tabbed browsing +and slim code. + +Frames are supported. You can have different file formats associated with +external viewers. `mailto:` and `telnet:` are supported via external clients. + +ELinks can handle both local files and remote URLs. The main supported remote +URL protocols are 'HTTP', 'HTTPS' (with SSL support compiled in) and 'FTP'. +Additional protocol support exists for 'BitTorrent' 'finger', 'Gopher', +'SMB' and 'NNTP'. + +The homepage of 'ELinks' can be found at http://elinks.cz/[], where the ELinks +manual is also hosted. + +OPTIONS +------- + +Most options can be set in the user interface or config file, so usually you +do not need to care about them. Note that this list is roughly equivalent to +the output of running ELinks with the option `--long-help`. + +include::{builddir}option-command.txt[] + +ENVIRONMENT VARIABLES +--------------------- + +COMSPEC, SHELL:: + + The shell used for File -> OS Shell on DOS/Windows and UNIX, + respectively. + +EDITOR:: + + The program to use for external editor (when editing textareas). + +ELINKS_CONFDIR:: + + The location of the directory containing configuration files. If not + set the default is `~/.elinks/`. + +ELINKS_TWTERM, LINKS_TWTERM:: + + The command to run when selecting File -> New window and if + `TWDISPLAY` is defined (default `twterm -e`) + +ELINKS_XTERM, LINKS_XTERM:: + + The command to run when selecting File -> New window and if `DISPLAY` + is defined (default `xterm -e`) + +FTP_PROXY, HTTP_PROXY, HTTPS_PROXY:: + + The host to proxy the various protocol traffic through. + +NO_PROXY:: + + A comma separated list of URLs which should not be proxied. + +HOME:: + + The path to the users home directory. Used when expanding `~/`. + +WWW_HOME:: + + Homepage location (as in man:lynx[1]). + +FILES +----- + +@sysconfdir@/elinks.conf:: + Site-wide configuration file. + +~/.elinks/elinks.conf:: + Per-user config file, loaded after site-wide configuration. + +~/.elinks/bookmarks:: + Bookmarks file. + +~/.elinks/cookies:: + Cookies file. + +~/.elinks/exmodehist:: + Exmode history file. + +~/.elinks/formhist:: + Form history file. + +~/.elinks/globhist:: + History file containing most recently visited URLs. + +~/.elinks/gotohist:: + GoTo URL dialog history file. + +~/.elinks/hooks.{js,lua,pl,py,rb,scm}:: + Browser scripting hooks. + +~/.elinks/searchhist:: + Search history file. + +~/.elinks/socket:: + Internal 'ELinks' socket for communication between its instances. + +~/.mailcap:: + Mappings of MIME types to external handlers. + +~/.mime.types:: + Mappings of file extensions to MIME types. + +Other files that ELinks uses from '~/.elinks/' includes the user defined CSS +stylesheet. The name of the file can set in the 'document.css.stylesheet' +option. + +PLATFORMS +--------- + +'ELinks' is known to work on 'Linux', 'FreeBSD', 'OpenBSD', 'Solaris', 'IRIX', +'HPUX', 'Digital Unix', 'AIX', 'OS/2', 'BeOS' and 'RISC OS'. Port for 'Win32' +is in state of beta testing. + +BUGS +---- + +Please report any other bugs you find to the either the ELinks mailing list at +mailto:elinks-users@linuxfromscratch.org[] or if you prefer enter them into +http://bugzilla.elinks.or.cz/[the bug tracking system]. More information about +how to get in contact with developers and getting help can be found on +http://elinks.or.cz/community.html[the community page]. + +LICENSE +------- + +'ELinks' is free software; you can redistribute it and/or modify it under the +terms of http://www.gnu.org/copyleft/gpl.html[the GNU General Public License] +as published by the Free Software Foundation; version 2 of the License. + +AUTHORS +------- + +The 'Links' browser - on which 'ELinks' is based - was written by Mikulas +Patocka mailto:mikulas@artax.karlin.mff.cuni.cz[]. 'ELinks' was written by +Petr Baudis mailto:pasky@ucw.cz[]. See file `AUTHORS` in the source tree for a +list of people contributing to this project. + +This manual page was written by Peter Gervai mailto:grin@tolna.net[], using +excerpts from a (yet?) unknown 'Links' fan for the 'Debian GNU/Linux system' +(but may be used by others). Contributions from Francis A. Holop. Extended, +clarified and made more up-to-date by Petr Baudis mailto:pasky@ucw.cz[]. +Updated by Zas mailto:zas@norz.org[]. The conversion to Asciidoc and trimming +was done by Jonas Fonseca mailto:fonseca@diku.dk[]. + +SEE ALSO +-------- + +man:elinkskeys[5], man:elinks.conf[5], man:links[1], man:lynx[1], man:w3m[1], +man:wget[1] + +//////////////////////////////////////////////////////////////////////////// +# vim: tabstop=4 shiftwidth=4 textwidth=76 +//////////////////////////////////////////////////////////////////////////// diff --git a/doc/elinks.conf.5.txt b/doc/elinks.conf.5.txt new file mode 100644 index 000000000..715d9027c --- /dev/null +++ b/doc/elinks.conf.5.txt @@ -0,0 +1,63 @@ +elinks.conf(5) +============== +:Description: ELinks configuration file + +NAME +---- +elinks.conf - ELinks configuration file + +SYNOPSIS +-------- +[verse] +set "