From f30583d605a00d23e7aa60cdca0e51c5494ae85c Mon Sep 17 00:00:00 2001 From: Kalle Olavi Niemitalo Date: Sat, 3 May 2008 18:29:20 +0300 Subject: [PATCH 1/8] Do not .gitignore doc/man/man5/*.5, which are already in Git. --- doc/man/.gitignore | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/man/.gitignore b/doc/man/.gitignore index ab81ec232..93d666925 100644 --- a/doc/man/.gitignore +++ b/doc/man/.gitignore @@ -1,3 +1,9 @@ index.bt manpage.links manpage.refs + +# elinks.conf.5 and elinkskeys.5 are first built in $(top_builddir)/doc/, +# where they should be ignored, but then "make update-man" can copy them +# to $(top_srcdir)/doc/man/man5/, where they should not be ignored. +# Override the "*.5" pattern listed in $(top_srcdir)/doc/.gitignore. +!*.5 From 604b99d5a404da300f31a90b15f0b3c4c221aab3 Mon Sep 17 00:00:00 2001 From: Kalle Olavi Niemitalo Date: Sat, 3 May 2008 18:11:51 +0300 Subject: [PATCH 2/8] help2xml: New script. The intention is to convert --config-help and --long-help outputs to DocBook XML and XHTML rather than AsciiDoc, so that the converter does not have to work around the intricate AsciiDoc syntax. However, this commit does not yet connect the script to doc/Makefile. XHTML could be generated from DocBook XML, but the script outputs it directly because our DocBook is primarily intended for manual pages and so does not have all the links that are useful in HTML. --- doc/tools/help2xml | 603 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 603 insertions(+) create mode 100755 doc/tools/help2xml diff --git a/doc/tools/help2xml b/doc/tools/help2xml new file mode 100755 index 000000000..f920625ac --- /dev/null +++ b/doc/tools/help2xml @@ -0,0 +1,603 @@ +#! /usr/bin/perl +# The copyright notice and license are in the POD at the bottom. + +use strict; +use warnings; +use Getopt::Long qw(GetOptions :config bundling gnu_compat); +use autouse 'Pod::Usage' => qw(pod2usage); + +sub show_version +{ + # This program has no version number, because it is only useful + # as part of the ELinks source tree. + print "help2xml (ELinks)\n"; + pod2usage({-verbose => 99, -sections => "COPYRIGHT AND LICENSE", + -exitval => 0}); +} + +# This script internally stores XML as nested arrays. Example: +# +# ['element', ['@id', "foo"], ['@dir', "ltr"], "text", ['subelement'], "more"] +# textmore +# +# A node is one of: +# - A string. This is just text and will be properly escaped when output. +# - A reference to an array where the first array element is a string that +# does not begin with '@'. This array represents an XML element. The +# other array elements are the attributes and content of the XML element. +# The current implementation does not require attributes to be listed +# before content. +# - A reference to an array where the first array element is a string that +# begins with '@'. This array represents an attribute of the parent XML +# element. The second array element is the value of the attribute; it +# must be a string. There should be no other array elements. +# +# So there is no way to represent XML declarations, processing instructions, +# comments, doctypes, or general entity references. +# +# The names of attributes in these nodes should be written in 'single quotes' +# because "@foo" would make Perl interpolate the value of the @foo array. +# The names of elements are also written in single quotes, by convention. + +# xml_output($outfh, $node): Write an XML node to a filehandle. +# +# $outfh: A reference to the output filehandle. +# +# $node: An XML node represented as described above. +# +# return: Unspecified. +sub xml_output +{ + no locale; + my ($outfh, $node) = @_; + if (ref($node) eq "ARRAY") { + my $gi = $node->[0]; + print $outfh "<$gi"; + my @content; + foreach my $child (@{$node}[1..$#$node]) { + if (ref($child) eq "ARRAY" and $child->[0] =~ /^@(.*)/) { + my $attrname = $1; + my $attrval = $child->[1]; + $attrval =~ s/([&"]|[^\0-~])/"&#".ord($1).";"/ge; + print $outfh " $attrname=\"$attrval\""; + } else { + push @content, $child; + } + } + if (@content) { + print $outfh ">"; + foreach my $child (@content) { + xml_output($outfh, $child); + } + print $outfh ""; + } else { + print $outfh "/>"; + } + } else { + $node =~ s/([&<>]|[^\0-~])/"&#".ord($1).";"/ge; + print $outfh $node; + } +} + +# xml_node_is_element($node, $gi): Check whether $node is an element +# that has the general identifier $gi. +sub xml_node_is_element +{ + my ($node, $gi) = @_; + return ref($node) eq "ARRAY" && $node->[0] eq $gi; +} + +# xml_element_attrs($node): Return the attributes of an XML element as +# a list. In scalar context, return the number of attributes instead. +sub xml_element_attrs +{ + no locale; + my ($node) = @_; + # $node->[0] is the general identifier of the element, a + # string, thus it won't match in the grep. + return grep { ref($_) eq "ARRAY" && $_->[0] =~ /^@/ } @$node; +} + +# xml_element_content($node): Return the content of an XML element as +# a list. Not recommended for use in scalar context. +sub xml_element_content +{ + no locale; + my ($node) = @_; + return grep { ref($_) ne "ARRAY" || $_->[0] !~ /^@/ } @$node[1..$#$node]; +} + +# apply_rules($node, $rules): Apply a list of transformations to an +# XML node. +# +# $node: An XML node represented as described above. +# +# $rules: A reference to an array of rules. The function applies the +# rules in order: the output of a rule can be further transformed with +# later rules but not with the same rule or earlier rules. Each rule +# in the array is a reference to a hash that has at least these keys: +# +# - FIND: A regular expression. The function recursively searches for +# matches in the content of $node, but not in names of elements, +# names of attributes, or contents of attributes. +# - REPLACE: A reference to a subroutine that returns a replacement for +# the match, as a list of nodes. This subroutine is called with +# no arguments, but it can use the $1 etc. variables that are set +# according to the regular expression. +# +# return: A list of nodes. +sub apply_rules +{ + my ($node, $rules) = @_; + my @output; + if (ref($node) eq "ARRAY") { + if ($node->[0] =~ /^@/) { + return $node; + } else { + return [$node->[0], + map({ apply_rules($_, $rules) } + @{$node}[1..$#$node])]; + } + } else { + my @rules = @$rules; + while (@rules) { + my $rule = shift @rules; + if ($node =~ $rule->{FIND}) { + # Using $` or $' anywhere in the program slows down all + # regexp matches. So get the values via substr instead. + my $pre = substr($node, 0, $-[0]); + my $post = substr($node, $+[0]); + my @replacement = $rule->{REPLACE}->(); # uses $1 etc. + return grep({ $_ ne "" } + map({ apply_rules($_, [@rules]) } + $pre, @replacement), + apply_rules($post, [$rule, @rules])); + } + } + return $node; + } +} + +# html_splice_p(@nodes): If the first node in @nodes is a paragraph, +# replace it with its content. The idea is to avoid extraneous +# vertical space in 'dd' and 'li' elements. +# +# return: The new list of nodes. +sub html_splice_p +{ + my @nodes = @_; + if (@nodes >= 1 + && xml_node_is_element($nodes[0], 'p') + && !xml_element_attrs($nodes[0])) { + splice(@nodes, 0, 1, xml_element_content($nodes[0])); + } + return @nodes; +} + +my %TemplatesDocBook = ( + # named DocBook elements + APPLICATION => sub { ['application', @_] }, + COMMAND => sub { ['command', @_] }, + ENVAR => sub { ['envar', @_] }, + FILENAME => sub { ['filename', @_] }, + GUIBUTTON => sub { ['guibutton', @_] }, + GUILABEL => sub { ['guilabel', @_] }, + LINK => sub { my $linkend = shift; ['link', ['@linkend', $linkend], @_] }, + LITERAL => sub { ['literal', @_] }, + PARAMETER => sub { ['parameter', @_] }, + SIMPARA => sub { ['simpara', @_] }, + ULINK => sub { my $url = shift; ['ulink', ['@url', $url], @_] }, + USERINPUT => sub { ['userinput', @_] }, + VARIABLELIST => sub { ['variablelist', @_] }, + + # not named after DocBook elements, but pretty simple anyway + CMDOPTTYPE => sub { ['replaceable', @_] }, + MANLINK => sub { my ($title, $volnum) = @_; + ['citerefentry', ['refentrytitle', $title], ['manvolnum', $volnum]] }, + SGMLATTR => sub { ['sgmltag', ['@class', "attribute"], @_] }, + SGMLELEMENT => sub { ['sgmltag', ['@class', "element"], @_] }, + STRONG => sub { ['emphasis', ['@role', "strong"], @_] }, + + # not so simple + CFGOPTENTRY => sub { my ($name, $type, $default, @children) = @_; + ['varlistentry', ['@id', $name], + ['term', ['literal', $name], " ", ['type', $type], " $default"], + ['listitem', @children]] }, + CMDOPTINFO => sub { my ($info) = @_; " $info" }, + CMDOPTNAME => sub { my $id = shift; ['option', ['@id', $id], @_] }, + CFGOPTTREE => sub { my ($name, $info, @children) = @_; + ['refsect2', ['@id', $name], + ['title', ['literal', $name], " ($info)"], + "\n", @children] }, + GUIMENUCHOICE => sub { my $item = pop; ['menuchoice', map(['guimenu', $_], @_), ['guimenuitem', $item]] }, + ITEMIZELIST => sub { ['itemizedlist', ['@spacing', "compact"], + map { ['listitem', $_], "\n" } @_] }, + USEREXAMPLE => sub { ['informalexample', ['simpara', ['userinput', @_]]], "\n" }, + VARLISTENTRY => sub { my ($termchildren, @itemchildren) = @_; + ['varlistentry', ['term', @$termchildren], + ['listitem', @itemchildren]] }, +); +my %TemplatesHTML = ( + # named DocBook elements + APPLICATION => sub { ['em', @_] }, + COMMAND => sub { ['kbd', @_] }, + ENVAR => sub { ['tt', @_] }, + FILENAME => sub { ['tt', @_] }, + GUIBUTTON => sub { "[ ", @_, " ]" }, + GUILABEL => sub { @_ }, + LINK => sub { my $linkend = shift; ['a', ['@href', "#$linkend"], @_] }, + LITERAL => sub { @_ }, + PARAMETER => sub { ['var', @_] }, + SIMPARA => sub { ['p', @_] }, + ULINK => sub { my $url = shift; ['a', ['@href', $url], @_] }, + USERINPUT => sub { ['kbd', @_] }, + VARIABLELIST => sub { ['dl', @_] }, + + # not named after DocBook elements, but pretty simple anyway + CMDOPTTYPE => sub { @_ }, + MANLINK => sub { my ($title, $volnum) = @_; + ['b', "$title($volnum)"] }, + SGMLATTR => sub { ['code', @_] }, + SGMLELEMENT => sub { ['code', @_] }, + STRONG => sub { ['strong', @_] }, + + # not so simple + CFGOPTENTRY => sub { my ($name, $type, $default, @children) = @_; + ['dt', ['@id', $name], "$name $type $default"], + ['dd', html_splice_p(@children)] }, + CMDOPTINFO => sub { my ($info) = @_; + if ($info =~ /^(\(alias for )([\w.]+)(\))$/) { + return " $1", ['a', ['@href', "elinks.conf.5.html#$2"], $2], $3; + } else { + return " $info"; + } }, + CMDOPTNAME => sub { my $id = shift; ['span', ['@id', $id], @_] }, + CFGOPTTREE => sub { my ($name, $info, @children) = @_; + ['h3', ['@id', $name], "$name ($info)"], + "\n", @children }, + GUIMENUCHOICE => sub { ['em', join(" \x{2192} ", @_)] }, + ITEMIZELIST => sub { ['ul', map { ['li', html_splice_p($_)], "\n" } @_] }, + USEREXAMPLE => sub { ['blockquote', ['p', ['kbd', @_]]], "\n" }, + VARLISTENTRY => sub { my ($termchildren, @itemchildren) = @_; + ['dt', @$termchildren], + ['dd', html_splice_p(@itemchildren)] }, +); + +sub optiondesc +{ + my ($pipe, $rules, $templates) = @_; + my @ret; + my $paragraph_text; + + my $end_paragraph = sub { + if (defined $paragraph_text) { + push @ret, $templates->{SIMPARA}($paragraph_text); + undef $paragraph_text; + } + }; + + while (defined($_) and /^ {12}/) { + # ' Cookie maximum age (in days):' + # ' -1 is use cookie's expiration date if any' + # ' 0 is force expiration at the end of session, ignoring cookie's' + # ' expiration date' + # ' 1+ is use cookie's expiration date, but limit age to the given' + # ' number of days' + if (/^ {12}((?:%|[+-]?\d).*)$/) { + $end_paragraph->(); + my @list_paragraphs; + do { + my $paragraph_text = ""; + do { + $paragraph_text .= "$1\n"; + $_ = <$pipe>; + } while (defined($_) and /^ {12}(\s+\S.*)$/); + chomp $paragraph_text; + push @list_paragraphs, $templates->{SIMPARA}($paragraph_text); + } while (defined($_) and /^ {12}((?:%|[+-]?\d).*)$/); + push @ret, $templates->{ITEMIZELIST}(@list_paragraphs); + } elsif (/^ {12}\t(\d.*)$/) { + $end_paragraph->(); + my @list_paragraphs; + do { + push @list_paragraphs, $templates->{SIMPARA}($1); + $_ = <$pipe>; + } while (defined($_) and /^ {12}\t(\d.*)$/); + push @ret, $templates->{ITEMIZELIST}(@list_paragraphs); + } elsif (/^ {12}\t(-.*)$/) { + $end_paragraph->(); + push @ret, $templates->{USEREXAMPLE}($1); + $_ = <$pipe>; + } elsif (/^ {12}\t(\w+)(\(.*\))\s+:\s+(\S.*)$/) { + $end_paragraph->(); + my @list_paragraphs; + my @remote_param_rules = ( + { FIND => qr(\b(URL|text)\b), + REPLACE => sub { $templates->{PARAMETER}($1) } }, + { FIND => qr(\b(new-tab|new-window|openBrowser)\b), + REPLACE => sub { $templates->{LITERAL}($1) } }, + ); + do { + push @list_paragraphs, $templates->{SIMPARA}( + $templates->{COMMAND}($1, apply_rules($2, \@remote_param_rules)), + ": $3"); + $_ = <$pipe>; + } while (defined($_) and /^ {12}\t(\w+)(\(.*\))\s+:\s+(\S.*)$/); + push @ret, $templates->{ITEMIZELIST}(@list_paragraphs); + } elsif (/^ {12}(.*\S.*)$/) { + $paragraph_text .= "$1\n"; + $_ = <$pipe>; + } else { + $end_paragraph->(); + $_ = <$pipe>; + } + } + $end_paragraph->(); + return map { apply_rules($_, $rules) } @ret; +} + +sub cmdopt_id +{ + no locale; + my ($option) = @_; + $option =~ s/^-+//; + $option =~ s/([^A-Za-z0-9-.])/sprintf('_%u', ord($1))/ge; + return "cmdopt:$option"; +} + +sub convert_config +{ + my ($outfh, $elinks, $option, $templates) = @_; + local $_; + + # The rules that apply to most of the output. + # See &apply_rules for the format. + my @shared_rules = ( + # files, commands, environment variables + { FIND => qr!"vi"!, + REPLACE => sub { $templates->{COMMAND}("vi") } }, + { FIND => qr!\b(xterm)\b!, + REPLACE => sub { $templates->{COMMAND}($1) } }, + { FIND => qr!((?:\$|\b)(?:EDITOR|FTP_PROXY|HOME|HTTP_PROXY|HTTPS_PROXY|MAILCAP|NNTPSERVER|NO_PROXY|TERM|WWW_HOME|X509_CLIENT_CERT))\b!, + REPLACE => sub { $templates->{ENVAR}($1) } }, + { FIND => qr!(~/\.elinks|/dev/urandom|/dev/zero|\bsetup\.h|\bmime\.types)\b!, + REPLACE => sub { $templates->{FILENAME}($1) } }, + { FIND => qr!\b(rename|fsync|strftime)\((\d+)\)!, + REPLACE => sub { $templates->{MANLINK}($1, $2) } }, + + # the rest + { FIND => qr!\b(http[46]?://[\w./+-]+?)(\.?)$!, + REPLACE => sub { $templates->{ULINK}($1, $1), $2 } }, + { FIND => qr!(ELinks bug (\d+))!, + REPLACE => sub { $templates->{ULINK}("http://bugzilla.elinks.cz/show_bug.cgi?id=$2", $1) } }, + { FIND => qr!\b(ELinks)\b!, + REPLACE => sub { $templates->{APPLICATION}($1) } }, + ); + + my @command_rules = ( + { FIND => qr!(-default-mime-type text/html)!, + REPLACE => sub { $templates->{USERINPUT}($1) } }, + + # This rule cannot be shared because the configuration option + # documentation does not have the anchors for the links. + { FIND => qr!(-?config-dir|-dump|-default-mime-type|-touch-files|-no-connect|-session-ring)!, + REPLACE => sub { $templates->{LINK}(cmdopt_id($1), $1) } }, + + @shared_rules); + + my @config_rules = ( + # non-ASCII characters + { FIND => qr!<->!, REPLACE => sub { "\x{2194}" } }, + { FIND => qr!(\s)-(\s)!, REPLACE => sub { "$1\x{2013}$2" } }, + { FIND => qr!(\s)---?(\s)!, REPLACE => sub { "$1\x{2014}$2" } }, + + # user interface + { FIND => qr!(Setup) -> (Terminal options)!, + REPLACE => sub { $templates->{GUIMENUCHOICE}($1, $2) } }, + { FIND => qr!\[ (Save) \]!, + REPLACE => sub { $templates->{GUIBUTTON}($1) } }, + { FIND => qr!\b(Goto URL)\b!, + REPLACE => sub { $templates->{GUILABEL}($1) } }, + + # SGML + { FIND => qr!\b(ACCESSKEY|TABINDEX)\b!, + REPLACE => sub { $templates->{SGMLATTR}($1) } }, + { FIND => qr!\b(IMG)\b!, + REPLACE => sub { $templates->{SGMLELEMENT}($1) } }, + { FIND => qr!\b(alt)/(title)\b!, + REPLACE => sub { $templates->{SGMLATTR}($1), "/", $templates->{SGMLATTR}($2) } }, + { FIND => qr!\b(alt)( attribute)!, + REPLACE => sub { $templates->{SGMLATTR}($1), $2 } }, + + # typography + { FIND => qr!\b_(not)_\b!, + REPLACE => sub { $templates->{STRONG}($1) } }, + + # This rule cannot be shared because the command-line option + # documentation does not have the anchors for the links. + { FIND => qr!\b(connection\.try_ipv6|cookies\.save|document\.browse\.minimum_refresh_time|document\.browse\.links\.color_dirs)\b!, + REPLACE => sub { $templates->{LINK}($1, $1) } }, + + @shared_rules); + + open my $pipe, "-|", $elinks, $option or die; + my $version = <$pipe>; + chomp $version; + $version =~ s/^ELinks ([-.\w]+).*$/$1/ or die "unusual version: $version"; + my @nodes; + $_ = <$pipe>; + while (defined($_)) { + if (/^$/) { + $_ = <$pipe>; + } elsif (/^Configuration options:$/) { + # The "Generated using" line is here at the top, because + # DocBook XML does not allow anything else to follow a + # refsect2 within a refsect1. + push @nodes, $templates->{SIMPARA}( + "Generated using output from ELinks version $version."); + $_ = <$pipe>; + while (defined($_)) { + if (/^$/) { + $_ = <$pipe>; + } elsif (/^ {2}(\S.*): \(([\w.-]+)\)$/) { + # ' Browsing: (document.browse)' + my ($tree_info, $tree_name) = ($1, $2); + my @tree_nodes; + $_ = <$pipe>; + push @tree_nodes, optiondesc($pipe, \@config_rules, $templates); + my @varlistentries; + while (defined($_)) { + if (/^$/) { + $_ = <$pipe>; + } elsif (/^ {4}(\S+) (\S+) (\(.*)$/) { + # ' cookies.save [0|1] (default: 1)' + my ($optname, $opttype, $optdefault) = ($1, $2, $3); + while ($optdefault =~ /^\([^"()]*"[^"]*$/s) { + # a special hack for document.dump.separator, + # which has newlines in the default value + my $contline = <$pipe>; + last unless defined($contline); + chomp $contline; + $optdefault .= "\n$contline"; + } + $_ = <$pipe>; + push @varlistentries, $templates->{CFGOPTENTRY}( + $optname, $opttype, $optdefault, + optiondesc($pipe, \@config_rules, $templates)); + } else { + last; + } + } + push @tree_nodes, $templates->{VARIABLELIST}(@varlistentries) + if @varlistentries; + push @nodes, $templates->{CFGOPTTREE}( + $tree_name, $tree_info, @tree_nodes); + } else { + last; + } + } + } elsif (/^Usage:/) { + $_ = <$pipe>; + } elsif (/^Options:$/) { + $_ = <$pipe>; + my @varlistentries; + my $name_rules = [ + { FIND => qr/([^,\s]+)/, + REPLACE => sub { $templates->{CMDOPTNAME}(cmdopt_id($1), $1) } }, + ]; + while (defined($_)) { + if (/^$/) { + $_ = <$pipe>; + } elsif (/^ {4}(\S+(?:,\s+\S+)*)(?:\s+([\[<]\S*))?(?:\s+(\(.*\)))?\s*$/) { + my @optnames = apply_rules($1, $name_rules); + my (@opttype, @optinfo); + @opttype = (" ", $templates->{CMDOPTTYPE}($2)) if defined($2); + @optinfo = $templates->{CMDOPTINFO}($3) if defined($3); + $_ = <$pipe>; + push @varlistentries, $templates->{VARLISTENTRY}( + [@optnames, @opttype, @optinfo], + optiondesc($pipe, \@command_rules, $templates)); + } else { + last; + } + } + push @nodes, $templates->{VARIABLELIST}(@varlistentries) + if @varlistentries; + push @nodes, $templates->{SIMPARA}( + "Generated using output from ELinks version $version."); + } else { + last; + } + } + die "parsing stopped at $.: $_" if defined($_); + xml_output($outfh, $_) foreach @nodes; +} + +GetOptions("help" => sub { pod2usage({-verbose => 1, -exitval => 0}) }, + "version" => \&show_version) + or exit 2; +print(STDERR "$0: wrong number of operands\n"), exit 2 if @ARGV != 2; +my ($ELinks, $Outfname) = @ARGV; + +my ($Option, $Templates); +$Option = "--config-help" if $Outfname =~ m(config[^/]*$); +$Option = "--long-help" if $Outfname =~ m(command[^/]*$); +$Templates = \%TemplatesDocBook if $Outfname =~ m(xml[^/]*$); +$Templates = \%TemplatesHTML if $Outfname =~ m(html[^/]*$); +unless ($Option and $Templates) { + print(STDERR "$0: name of output file does not indicate its content: $Outfname\n"); + exit 2; +} +open my $outfh, ">", $Outfname or die "$Outfname: $!\n"; +convert_config $outfh, $ELinks, $Option, $Templates; +close $outfh or die "$Outfname: $!\n"; + +__END__ + +=head1 NAME + +help2xml - Convert help output from ELinks to DocBook XML or XHTML. + +=head1 SYNOPSIS + +B F<.../src/elinks> F<.../option-command.frag.xml> + +B F<.../src/elinks> F<.../option-config.frag.xml> + +B F<.../src/elinks> F<.../option-command.frag.xhtml> + +B F<.../src/elinks> F<.../option-config.frag.xhtml> + +=head1 DESCRIPTION + +B runs B or B to +get the documentation of command-line or configuration options from +the elinks executable, and converts it to a fragment of DocBook XML or +XHTML. In the build system, these fragments are then included in the +DocBook and XHTML versions of the L and L +manual pages. + +=head1 ARGUMENTS + +=over + +=item F<.../src/elinks> + +The B executable file that B runs in order to +get the documentation. + +=item F<.../option-command.frag.xml> + +=item F<.../option-config.frag.xml> + +=item F<.../option-command.frag.xhtml> + +=item F<.../option-config.frag.xhtml> + +The output file to which B writes the DocBook XML or +XHTML fragment. The basename of this file must include the word +"command" for command-line options, or "config" for configuration +options. It must also include "xml" for Docbook XML, or "html" for +XHTML. + +=back + +=head1 AUTHOR + +Kalle Olavi Niemitalo + +=head1 COPYRIGHT AND LICENSE + +Copyright (c) 2008 Kalle Olavi Niemitalo. + +Permission to use, copy, modify, and distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. From 573036a4032c7754a2af2d28d6c96a6c5d38623b Mon Sep 17 00:00:00 2001 From: Kalle Olavi Niemitalo Date: Sat, 3 May 2008 18:30:26 +0300 Subject: [PATCH 3/8] Generate DocBook and XHTML with help2xml. The older help2doc script is no longer used for anything. To make future cherry-picking easier, this commit does not include the resulting changes in generated files. --- doc/Makefile | 24 ++++++++++++++++-------- doc/elinks.1.txt | 9 ++++++++- doc/elinks.conf.5.txt | 10 +++++++++- 3 files changed, 33 insertions(+), 10 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index e516bbbdc..792591c9d 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -26,8 +26,6 @@ TXT_DOCS_NOINSTALL = \ features.txt \ keymap-actions.txt \ keymap-defaults.txt \ - option-command.txt \ - option-config.txt TXT_DOCS_ASIS = \ python.txt @@ -110,7 +108,7 @@ install-local: # Generated asciidoc files # Scripts and Dependencies -HELP2DOC = $(srcdir)tools/help2doc +HELP2XML = $(srcdir)tools/help2xml CONF2DOC = $(srcdir)tools/conf2doc KEYS2DOC = $(srcdir)tools/keys2doc ELINKS = $(top_builddir)/src/elinks @@ -123,8 +121,8 @@ LOCALES = LC_ALL=C LANGUAGE=en # 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_help2xml = ' [$(LINK_COLOR)HELP2XML$(END_COLOR)] $(RELPATH)$@' + cmd_help2xml = $(LOCALES) $(HELP2XML) $(ELINKS) $@ quiet_cmd_conf2doc = ' [$(LINK_COLOR)CONF2DOC$(END_COLOR)] $(RELPATH)$@' cmd_conf2doc = $(LOCALES) $(CONF2DOC) $(FEATURES) > $@ @@ -138,9 +136,11 @@ features.txt: $(FEATURES) $(CONF2DOC) keymap-%.txt: $(KBDBIND) $(KEYS2DOC) $(call cmd,keys2doc) -option-%.txt: $(ELINKS) $(HELP2DOC) - $(call cmd,help2doc) +option-%.frag.xml: $(ELINKS) $(HELP2XML) + $(call cmd,help2xml) +option-%.frag.xhtml: $(ELINKS) $(HELP2XML) + $(call cmd,help2xml) ############################################################################# # Build commands and macros @@ -166,7 +166,7 @@ backend = $(if $(findstring .xml,$@),docbook,xhtml11) outdir = $(if $(findstring -chunked,$@),$@,.) # Loosely track dependencies via asciidoc includes. -asciidoc_dep = sed -n 's/[{]builddir}//g;s@include::\(.*\)\[.*@$@: $< \1@p' < $< > .deps/$(@F).asciidoc +asciidoc_dep = sed -n 's/[{]builddir}//g;s@include1\{0,1\}::\(.*\)\[.*@$@: $< \1@p' < $< > .deps/$(@F).asciidoc -include .deps/*.asciidoc @@ -182,6 +182,14 @@ asciidoc_dep = sed -n 's/[{]builddir}//g;s@include::\(.*\)\[.*@$@: $< \1@p' < $< $(call cmd,asciidoc,docbook) @-$(call asciidoc_dep) +# asciidoc_dep above also generates these dependencies, but it runs +# only after asciidoc has succeeded, which won't happen if the files +# are missing. +elinks.1.xml: option-command.frag.xml +elinks.conf.5.xml: option-config.frag.xml +elinks.1.html: option-command.frag.xhtml +elinks.conf.5.html: option-config.frag.xhtml + %.1: %.1.xml $(call cmd,xmlto,man) diff --git a/doc/elinks.1.txt b/doc/elinks.1.txt index 231b879fc..71fceefdb 100644 --- a/doc/elinks.1.txt +++ b/doc/elinks.1.txt @@ -35,7 +35,14 @@ 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[] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +ifdef::backend-docbook[] +include1::{builddir}option-command.frag.xml[] +endif::backend-docbook[] +ifdef::backend-xhtml11[] +include1::{builddir}option-command.frag.xhtml[] +endif::backend-xhtml11[] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ENVIRONMENT VARIABLES --------------------- diff --git a/doc/elinks.conf.5.txt b/doc/elinks.conf.5.txt index 9402f6e16..994a56f8c 100644 --- a/doc/elinks.conf.5.txt +++ b/doc/elinks.conf.5.txt @@ -56,7 +56,15 @@ Some sample settings: OPTIONS ------- -include::{builddir}option-config.txt[] + +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +ifdef::backend-docbook[] +include1::{builddir}option-config.frag.xml[] +endif::backend-docbook[] +ifdef::backend-xhtml11[] +include1::{builddir}option-config.frag.xhtml[] +endif::backend-xhtml11[] +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ SEE ALSO -------- From 34bdddbd873e0ad7191a1d0a9fa152b5fd2c1650 Mon Sep 17 00:00:00 2001 From: Kalle Olavi Niemitalo Date: Sat, 3 May 2008 20:37:44 +0300 Subject: [PATCH 4/8] Regenerated manpages using help2xml --- doc/man/man1/elinks.1.in | 143 ++- doc/man/man5/elinks.conf.5 | 2235 +++++++++++++++++------------------- 2 files changed, 1101 insertions(+), 1277 deletions(-) diff --git a/doc/man/man1/elinks.1.in b/doc/man/man1/elinks.1.in index 0951479bd..3b0a55640 100644 --- a/doc/man/man1/elinks.1.in +++ b/doc/man/man1/elinks.1.in @@ -1,11 +1,11 @@ .\" Title: elinks .\" Author: .\" Generator: DocBook XSL Stylesheets v1.72.0 -.\" Date: 03/08/2008 +.\" Date: 05/03/2008 .\" Manual: The Elinks text-browser .\" Source: ELinks 0.12.GIT .\" -.TH "ELINKS" "1" "03/08/2008" "ELinks 0.12.GIT" "The Elinks text\-browser" +.TH "ELINKS" "1" "05/03/2008" "ELinks 0.12.GIT" "The Elinks text\-browser" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -28,221 +28,210 @@ The homepage of \fIELinks\fR can be found at , where the ELin 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. .sp .PP -\-anonymous [0|1] (default: 0) +\fB\-anonymous\fR \fI[0|1]\fR (default: 0) .RS 4 Restricts -\fIELinks\fR +ELinks so it can run on an anonymous account. Local file browsing, downloads, and modification of options will be disabled. Execution of viewers is allowed, but entries in the association table can't be added or modified. .RE .PP -\-auto\-submit [0|1] (default: 0) +\fB\-auto\-submit\fR \fI[0|1]\fR (default: 0) .RS 4 Automatically submit the first form in the given URLs. .RE .PP -\-base\-session (default: 0) +\fB\-base\-session\fR \fI\fR (default: 0) .RS 4 Used internally when opening -\fIELinks\fR +ELinks instances in new windows. The ID maps to information that will be used when creating the new instance. You don't want to use it. .RE .PP -\-config\-dir (default: "") +\fB\-config\-dir\fR \fI\fR (default: "") .RS 4 Path of the directory -\fIELinks\fR +ELinks will read and write its config and runtime state files to instead of -~/.elinks. If the path does not begin with a '/' it is assumed to be relative to your -\fIHOME\fR +\fI~/.elinks\fR. If the path does not begin with a '/' it is assumed to be relative to your +\fBHOME\fR directory. .RE .PP -\-config\-dump +\fB\-config\-dump\fR .RS 4 Print a configuration file with options set to the built\-in defaults to stdout. .RE .PP -\-config\-file (default: "elinks.conf") +\fB\-config\-file\fR \fI\fR (default: "elinks.conf") .RS 4 -Name of the configuration file that all configuration options will be read from and written to. It should be relative to config\-dir. +Name of the configuration file that all configuration options will be read from and written to. It should be relative to +config\-dir. .RE .PP -\-config\-help +\fB\-config\-help\fR .RS 4 Print help for configuration options and exit. .RE .PP -\-default\-mime\-type (alias for mime.default_type) +\fB\-default\-mime\-type\fR (alias for mime.default_type) .RS 4 The default MIME type used for documents of unknown type. .RE .PP -\-default\-keys [0|1] (default: 0) +\fB\-default\-keys\fR \fI[0|1]\fR (default: 0) .RS 4 When set, all keybindings from configuration files will be ignored. It forces use of default keybindings and will reset user\-defined ones on save. .RE .PP -\-dump [0|1] (default: 0) +\fB\-dump\fR \fI[0|1]\fR (default: 0) .RS 4 Print formatted plain\-text versions of given URLs to stdout. .RE .PP -\-dump\-charset (alias for document.dump.codepage) +\fB\-dump\-charset\fR (alias for document.dump.codepage) .RS 4 Codepage used when formatting dump output. .RE .PP -\-dump\-color\-mode (alias for document.dump.color_mode) +\fB\-dump\-color\-mode\fR (alias for document.dump.color_mode) .RS 4 Color mode used with \-dump. .RE .PP -\-dump\-width (alias for document.dump.width) +\fB\-dump\-width\fR (alias for document.dump.width) .RS 4 Width of the dump output. .RE .PP -\-eval +\fB\-eval\fR .RS 4 Specify configuration file directives on the command\-line which will be evaluated after all configuration files has been read. Example usage: -.sp -.RS 4 -.nf -\-eval 'set protocol.file.allow_special_files = 1' -.fi -.RE +\fB\-eval 'set protocol.file.allow_special_files = 1'\fR .RE .PP -\-force\-html +\fB\-force\-html\fR .RS 4 Makes -\fIELinks\fR +ELinks assume documents of unknown types are HTML. Useful when using -\fIELinks\fR +ELinks as an external viewer from MUAs. This is equivalent to -\-default\-mime\-type -text/html. +\fB\-default\-mime\-type\fR\fB text/html\fR. .RE .PP -\-?, \-h, \-help +\fB\-?\fR, \fB\-h\fR, \fB\-help\fR .RS 4 Print usage help and exit. .RE .PP -\-localhost [0|1] (default: 0) +\fB\-localhost\fR \fI[0|1]\fR (default: 0) .RS 4 Restricts -\fIELinks\fR +ELinks to work offline and only connect to servers with local addresses (ie. 127.0.0.1). No connections to remote servers will be permitted. .RE .PP -\-long\-help +\fB\-long\-help\fR .RS 4 Print detailed usage help and exit. .RE .PP -\-lookup +\fB\-lookup\fR .RS 4 Look up specified host and print all DNS resolved IP addresses. .RE .PP -\-no\-connect [0|1] (default: 0) +\fB\-no\-connect\fR \fI[0|1]\fR (default: 0) .RS 4 Run -\fIELinks\fR +ELinks as a separate instance instead of connecting to an existing instance. Note that normally no runtime state files (bookmarks, history, etc.) are written to the disk when this option is used. See also \-touch\-files. .RE .PP -\-no\-home [0|1] (default: 0) +\fB\-no\-home\fR \fI[0|1]\fR (default: 0) .RS 4 -Disables creation and use of files in the user specific home configuration directory (~/.elinks). It forces default configuration values to be used and disables saving of runtime state files. +Disables creation and use of files in the user specific home configuration directory (\fI~/.elinks\fR). It forces default configuration values to be used and disables saving of runtime state files. .RE .PP -\-no\-numbering (alias for document.dump.numbering) +\fB\-no\-numbering\fR (alias for document.dump.numbering) .RS 4 Prevents printing of link number in dump output. Note that this really affects only \-dump, nothing else. .RE .PP -\-no\-references (alias for document.dump.references) +\fB\-no\-references\fR (alias for document.dump.references) .RS 4 Prevents printing of references (URIs) of document links in dump output. Note that this really affects only \-dump, nothing else. .RE .PP -\-remote +\fB\-remote\fR .RS 4 Control a remote -\fIELinks\fR +ELinks instance by passing commands to it. The option takes an additional argument containing the method which should be invoked and any parameters that should be passed to it. For ease of use, the additional method argument can be omitted in which case any URL arguments will be opened in new tabs in the remote instance. Following is a list of the supported methods: .sp .RS 4 -\h'-04'\(bu\h'+03' -ping(): look for a remote instance +\h'-04'\(bu\h'+03'\fBping()\fR: look for a remote instance .RE .sp .RS 4 -\h'-04'\(bu\h'+03' -openURL(): prompt URL in current tab +\h'-04'\(bu\h'+03'\fBopenURL()\fR: prompt URL in current tab .RE .sp .RS 4 -\h'-04'\(bu\h'+03' -openURL(URL): open URL in current tab +\h'-04'\(bu\h'+03'\fBopenURL(\fR\fB\fIURL\fR\fR\fB)\fR: open URL in current tab .RE .sp .RS 4 -\h'-04'\(bu\h'+03' -openURL(URL, new\-tab): open URL in new tab +\h'-04'\(bu\h'+03'\fBopenURL(\fR\fB\fIURL\fR\fR\fB, \fR\fBnew\-tab\fR\fB)\fR: open URL in new tab .RE .sp .RS 4 -\h'-04'\(bu\h'+03' -openURL(URL, new\-window): open URL in new window +\h'-04'\(bu\h'+03'\fBopenURL(\fR\fB\fIURL\fR\fR\fB, \fR\fBnew\-window\fR\fB)\fR: open URL in new window .RE .sp .RS 4 -\h'-04'\(bu\h'+03' -addBookmark(URL): bookmark URL +\h'-04'\(bu\h'+03'\fBaddBookmark(\fR\fB\fIURL\fR\fR\fB)\fR: bookmark URL .RE .sp .RS 4 -\h'-04'\(bu\h'+03' -infoBox(text): show text in a message box +\h'-04'\(bu\h'+03'\fBinfoBox(\fR\fB\fItext\fR\fR\fB)\fR: show text in a message box .RE .sp .RS 4 -\h'-04'\(bu\h'+03' -xfeDoCommand(openBrowser): open new window +\h'-04'\(bu\h'+03'\fBxfeDoCommand(\fR\fBopenBrowser\fR\fB)\fR: open new window .RE .RE .PP -\-session\-ring (default: 0) +\fB\-session\-ring\fR \fI\fR (default: 0) .RS 4 ID of session ring this -\fIELinks\fR +ELinks session should connect to. -\fIELinks\fR +ELinks works in so\-called session rings, whereby all instances of -\fIELinks\fR +ELinks are interconnected and share state (cache, bookmarks, cookies, and so on). By default, all -\fIELinks\fR -instances connect to session ring 0. You can change that behaviour with this switch and form as many session rings as you want. Obviously, if the session\-ring with this number doesn't exist yet, it's created and this 'ELinks' instance will become the master instance (that usually doesn't matter for you as a user much). Note that you usually don't want to use this unless you're a developer and you want to do some testing \- if you want the -\fIELinks\fR +ELinks +instances connect to session ring 0. You can change that behaviour with this switch and form as many session rings as you want. Obviously, if the session\-ring with this number doesn't exist yet, it's created and this +ELinks +instance will become the master instance (that usually doesn't matter for you as a user much). Note that you usually don't want to use this unless you're a developer and you want to do some testing \- if you want the +ELinks instances each running standalone, rather use the \-no\-connect command\-line option. Also note that normally no runtime state files are written to the disk when this option is used. See also \-touch\-files. .RE .PP -\-source [0|1] (default: 0) +\fB\-source\fR \fI[0|1]\fR (default: 0) .RS 4 Print given URLs in source form to stdout. .RE .PP -\-touch\-files [0|1] (default: 0) +\fB\-touch\-files\fR \fI[0|1]\fR (default: 0) .RS 4 When enabled, runtime state files (bookmarks, history, etc.) are written to disk, even when \-no\-connect @@ -251,27 +240,27 @@ or is used. The option has no effect if not used in conjunction with any of these options. .RE .PP -\-verbose (default: 1) +\fB\-verbose\fR \fI\fR (default: 1) .RS 4 The verbose level controls what messages are shown at start up and while running: .sp .RS 4 -\h'-04'\(bu\h'+03'0: means only show serious errors +\h'-04'\(bu\h'+03'0 means only show serious errors .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: means show serious errors and warnings +\h'-04'\(bu\h'+03'1 means show serious errors and warnings .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: means show all messages +\h'-04'\(bu\h'+03'2 means show all messages .RE .RE .PP -\-version +\fB\-version\fR .RS 4 Print -\fIELinks\fR +ELinks version information and exit. .RE Generated using output from ELinks version 0.12.GIT. diff --git a/doc/man/man5/elinks.conf.5 b/doc/man/man5/elinks.conf.5 index 5b7185e9a..650aa1aeb 100644 --- a/doc/man/man5/elinks.conf.5 +++ b/doc/man/man5/elinks.conf.5 @@ -1,11 +1,11 @@ .\" Title: elinks.conf .\" Author: .\" Generator: DocBook XSL Stylesheets v1.72.0 -.\" Date: 03/23/2008 +.\" Date: 05/03/2008 .\" Manual: ELinks configuration file .\" Source: ELinks 0.12.GIT .\" -.TH "ELINKS.CONF" "5" "03/23/2008" "ELinks 0.12.GIT" "ELinks configuration file" +.TH "ELINKS.CONF" "5" "05/03/2008" "ELinks 0.12.GIT" "ELinks configuration file" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -49,3124 +49,2959 @@ set protocol.user.mailto.unix = "mutt %h \-s \e"%s\e"" .fi .RE .SH "OPTIONS" -.PP -bookmarks -.RS 4 +Generated using output from ELinks version 0.12.GIT. +.sp +.SS "bookmarks (Bookmarks)" Bookmark options. -.RE +.sp .PP -bookmarks.file_format (default: 0) +bookmarks.file_format \fB\fR (default: 0) .RS 4 File format for bookmarks (affects both reading and saving): .sp .RS 4 -\h'-04'\(bu\h'+03'0: is the default native -\fIELinks\fR +\h'-04'\(bu\h'+03'0 is the default native +ELinks format .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: is XBEL universal XML bookmarks format (\fIELinks\fR -bug 153: NO NATIONAL CHARS SUPPORT!) +\h'-04'\(bu\h'+03'1 is XBEL universal XML bookmarks format (\fIELinks bug 153\fR\&[1]: NO NATIONAL CHARS SUPPORT!) .RE .RE .PP -bookmarks.folder_state [0|1] (default: 1) +bookmarks.folder_state \fB[0|1]\fR (default: 1) .RS 4 When saving bookmarks also store whether folders are expanded or not, so the look of the bookmark dialog is kept across -\fIELinks\fR +ELinks sessions. If disabled all folders will appear unexpanded next time -\fIELinks\fR +ELinks is run. .RE -.PP -config -.RS 4 +.SS "config (Configuration system)" Configuration handling options. -.RE +.sp .PP -config.comments (default: 3) +config.comments \fB\fR (default: 3) .RS 4 Amount of comments automatically written to the config file: .sp .RS 4 -\h'-04'\(bu\h'+03'0: is no comments are written +\h'-04'\(bu\h'+03'0 is no comments are written .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: is only the "blurb" (name+type) is written +\h'-04'\(bu\h'+03'1 is only the "blurb" (name+type) is written .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: is only the description is written +\h'-04'\(bu\h'+03'2 is only the description is written .RE .sp .RS 4 -\h'-04'\(bu\h'+03'3: is full comments are written +\h'-04'\(bu\h'+03'3 is full comments are written .RE .RE .PP -config.indentation (default: 2) +config.indentation \fB\fR (default: 2) .RS 4 Shift width of one indentation level in the configuration file. Zero means that no indentation is performed at all when saving the configuration. .RE .PP -config.saving_style (default: 3) +config.saving_style \fB\fR (default: 3) .RS 4 Determines what happens when you tell -\fIELinks\fR +ELinks to save options: .sp .RS 4 -\h'-04'\(bu\h'+03'0: is only values of current options are altered +\h'-04'\(bu\h'+03'0 is only values of current options are altered .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: is values of current options are altered and missing options are added at the end of the file +\h'-04'\(bu\h'+03'1 is values of current options are altered and missing options are added at the end of the file .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: is the configuration file is rewritten from scratch +\h'-04'\(bu\h'+03'2 is the configuration file is rewritten from scratch .RE .sp .RS 4 -\h'-04'\(bu\h'+03'3: is values of current options are altered and missing options CHANGED during this -\fIELinks\fR +\h'-04'\(bu\h'+03'3 is values of current options are altered and missing options CHANGED during this +ELinks session are added at the end of the file .RE .RE .PP -config.i18n [0|1] (default: 0) +config.i18n \fB[0|1]\fR (default: 0) .RS 4 If set to 1, comments in the configuration file will be translated to the language used by UI. Note that if you have different language set in different terminals, the language used in the configuration file MAY be the same as on the terminal where you saved the file, but it should be generally considered unpredictable. .RE .PP -config.saving_style_w [0|1] (default: 0) +config.saving_style_w \fB[0|1]\fR (default: 0) .RS 4 This is internal option used when displaying a warning about obsolete config.saving_style. You shouldn't touch it. .RE .PP -config.show_template [0|1] (default: 0) +config.show_template \fB[0|1]\fR (default: 0) .RS 4 Show template options in autocreated trees in the options manager and save them to the configuration file. .RE -.PP -connection -.RS 4 +.SS "connection (Connections)" Connection options. -.RE +.sp .PP -connection.async_dns [0|1] (default: 1) +connection.async_dns \fB[0|1]\fR (default: 1) .RS 4 Whether to use asynchronous DNS resolving. .RE .PP -connection.max_connections (default: 10) +connection.max_connections \fB\fR (default: 10) .RS 4 Maximum number of concurrent connections. .RE .PP -connection.max_connections_to_host (default: 2) +connection.max_connections_to_host \fB\fR (default: 2) .RS 4 Maximum number of concurrent connections to a given host. .RE .PP -connection.receive_timeout (default: 120) +connection.receive_timeout \fB\fR (default: 120) .RS 4 Receive timeout (in seconds). .RE .PP -connection.retries (default: 3) +connection.retries \fB\fR (default: 3) .RS 4 Number of tries to establish a connection. Zero means try forever. .RE .PP -connection.try_ipv4 [0|1] (default: 1) +connection.try_ipv4 \fB[0|1]\fR (default: 1) .RS 4 -Whether to try to connect to a host over IPv4. Note that if connection.try_ipv6 is enabled too, it takes precedence. And better do not touch this at all unless you are sure what are you doing. Note that you can also force a given protocol to be used on a per\-connection basis by using a URL in the style of e.g. http4://elinks.cz/. +Whether to try to connect to a host over IPv4. Note that if +connection.try_ipv6 +is enabled too, it takes precedence. And better do not touch this at all unless you are sure what are you doing. Note that you can also force a given protocol to be used on a per\-connection basis by using a URL in the style of e.g. +\fIhttp4://elinks.cz/\fR. .RE .PP -connection.try_ipv6 [0|1] (default: 1) +connection.try_ipv6 \fB[0|1]\fR (default: 1) .RS 4 -Whether to try to connect to a host over IPv6. Note that you can also force a given protocol to be used on a per\-connection basis by using a URL in the style of e.g. http6://elinks.cz/. +Whether to try to connect to a host over IPv6. Note that you can also force a given protocol to be used on a per\-connection basis by using a URL in the style of e.g. +\fIhttp6://elinks.cz/\fR. .RE .PP -connection.unrestartable_receive_timeout (default: 600) +connection.unrestartable_receive_timeout \fB\fR (default: 600) .RS 4 Timeout for non\-restartable connections (in seconds). .RE -.PP -connection.ssl -.RS 4 +.SS "connection.ssl (SSL)" SSL options. -.RE +.sp .PP -connection.ssl.cert_verify [0|1] (default: 0) +connection.ssl.cert_verify \fB[0|1]\fR (default: 0) .RS 4 Verify the peer's SSL certificate. Note that this needs extensive configuration of OpenSSL by the user. .RE -.PP -connection.ssl.client_cert -.RS 4 +.SS "connection.ssl.client_cert (Client Certificates)" X509 client certificate options. -.RE +.sp .PP -connection.ssl.client_cert.enable [0|1] (default: 0) +connection.ssl.client_cert.enable \fB[0|1]\fR (default: 0) .RS 4 Enable or not the sending of X509 client certificates to servers which request them. .RE .PP -connection.ssl.client_cert.file (default: "") +connection.ssl.client_cert.file \fB\fR (default: "") .RS 4 -The location of a file containing the client certificate and unencrypted private key in PEM format. If unset, the file pointed to by the X509_CLIENT_CERT variable is used instead. +The location of a file containing the client certificate and unencrypted private key in PEM format. If unset, the file pointed to by the +\fBX509_CLIENT_CERT\fR +variable is used instead. .RE -.PP -cookies -.RS 4 +.SS "cookies (Cookies)" Cookies options. -.RE +.sp .PP -cookies.accept_policy (default: 2) +cookies.accept_policy \fB\fR (default: 2) .RS 4 Cookies accepting policy: .sp .RS 4 -\h'-04'\(bu\h'+03'0: is accept no cookies +\h'-04'\(bu\h'+03'0 is accept no cookies .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: is ask for confirmation before accepting cookie +\h'-04'\(bu\h'+03'1 is ask for confirmation before accepting cookie .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: is accept all cookies +\h'-04'\(bu\h'+03'2 is accept all cookies .RE .RE .PP -cookies.max_age (default: \-1) +cookies.max_age \fB\fR (default: \-1) .RS 4 Cookie maximum age (in days): .sp .RS 4 -\h'-04'\(bu\h'+03'\-1: is use cookie's expiration date if any +\h'-04'\(bu\h'+03'\-1 is use cookie's expiration date if any .RE .sp .RS 4 -\h'-04'\(bu\h'+03'0: is force expiration at the end of session, ignoring cookie's expiration date +\h'-04'\(bu\h'+03'0 is force expiration at the end of session, ignoring cookie's expiration date .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1+: is use cookie's expiration date, but limit age to the given number of days +\h'-04'\(bu\h'+03'1+ is use cookie's expiration date, but limit age to the given number of days .RE .RE .PP -cookies.paranoid_security [0|1] (default: 0) +cookies.paranoid_security \fB[0|1]\fR (default: 0) .RS 4 When enabled, we'll require three dots in cookies domain for all non\-international domains (instead of just two dots). Some countries have generic second level domains (eg. .com.pl, .co.uk) and allowing sites to set cookies for these generic domains could potentially be very bad. Note, it is off by default as it breaks a lot of sites. .RE .PP -cookies.save [0|1] (default: 1) +cookies.save \fB[0|1]\fR (default: 1) .RS 4 Whether cookies should be loaded from and saved to disk. .RE .PP -cookies.resave [0|1] (default: 1) +cookies.resave \fB[0|1]\fR (default: 1) .RS 4 Save cookies after each change in cookies list? No effect when cookie saving (cookies.save) is off. .RE -.PP -document -.RS 4 +.SS "document (Document)" Document options. -.RE -.PP -document.browse -.RS 4 +.sp +.SS "document.browse (Browsing)" Document browsing options (mainly interactivity). -.RE +.sp .PP -document.browse.margin_width (default: 3) +document.browse.margin_width \fB\fR (default: 3) .RS 4 Horizontal text margin. .RE .PP -document.browse.refresh [0|1] (default: 1) +document.browse.refresh \fB[0|1]\fR (default: 1) .RS 4 -Automatically follow document\-specified refresh directives (\fI refresh\fR -tags). Web\-page authors use these to instruct the browser to reload a document at a given interval or to load another page. Regardless of the value the refresh URI is accessible as a link. Use the document.browse.minimum_refresh_time to control the minimum number of seconds a refresh will wait. +Automatically follow document\-specified refresh directives (' refresh' tags). Web\-page authors use these to instruct the browser to reload a document at a given interval or to load another page. Regardless of the value the refresh URI is accessible as a link. Use the +document.browse.minimum_refresh_time +to control the minimum number of seconds a refresh will wait. .RE .PP -document.browse.minimum_refresh_time (default: 1000) +document.browse.minimum_refresh_time \fB\fR (default: 1000) .RS 4 The minimum number of milliseconds that should pass before refreshing. If set to zero the document refresh time is used unchanged. It can fix going back in history for some sites that use refreshing with zero values. .RE .PP -document.browse.table_move_order [0|1] (default: 0) +document.browse.table_move_order \fB[0|1]\fR (default: 0) .RS 4 Move by columns in table, instead of rows. .RE -.PP -document.browse.accesskey -.RS 4 +.SS "document.browse.accesskey (Access keys)" Options for handling of link access keys. An HTML document can use the ACCESSKEY attribute to assign an access key to an element. When an access key is pressed, the corresponding element will be given focus. -.RE +.sp .PP -document.browse.accesskey.auto_follow [0|1] (default: 0) +document.browse.accesskey.auto_follow \fB[0|1]\fR (default: 0) .RS 4 -Automatically follow a link or submit a form if appropriate accesskey is pressed \- this is the standard behaviour, but it's considered dangerous. +Automatically follow a link or submit a form if appropriate accesskey is pressed \(en this is the standard behaviour, but it's considered dangerous. .RE .PP -document.browse.accesskey.display [0|1] (default: 0) +document.browse.accesskey.display \fB[0|1]\fR (default: 0) .RS 4 Display access key in link info. .RE .PP -document.browse.accesskey.priority (default: 0) +document.browse.accesskey.priority \fB\fR (default: 0) .RS 4 Priority of 'accesskey' HTML attribute: .sp .RS 4 -\h'-04'\(bu\h'+03'0: is first try all normal bindings; if it fails, check accesskey +\h'-04'\(bu\h'+03'0 is first try all normal bindings; if it fails, check accesskey .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: is first try only frame bindings; if it fails, check accesskey +\h'-04'\(bu\h'+03'1 is first try only frame bindings; if it fails, check accesskey .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: is first check accesskey (this can be dangerous) +\h'-04'\(bu\h'+03'2 is first check accesskey (this can be dangerous) .RE .RE -.PP -document.browse.forms -.RS 4 +.SS "document.browse.forms (Forms)" Options for handling of the forms interaction. -.RE +.sp .PP -document.browse.forms.auto_submit [0|1] (default: 1) +document.browse.forms.auto_submit \fB[0|1]\fR (default: 1) .RS 4 Automagically submit a form when enter is pressed with a text field selected. .RE .PP -document.browse.forms.confirm_submit [0|1] (default: 1) +document.browse.forms.confirm_submit \fB[0|1]\fR (default: 1) .RS 4 Ask for confirmation when submitting a form. .RE .PP -document.browse.forms.input_size (default: 20) +document.browse.forms.input_size \fB\fR (default: 20) .RS 4 Default form input size if none is specified. .RE .PP -document.browse.forms.insert_mode [0|1] (default: 1) +document.browse.forms.insert_mode \fB[0|1]\fR (default: 1) .RS 4 The setting for this option affects how key presses are handled when one selects a text\-input form\-field. When enabled, one must explicitly 'enter' a selected text\-field to edit it; this prevents text fields from capturing key presses, such as presses of a scroll key, when it is inadvertently selected. When disabled, key presses are always inserted into a selected text field. .RE .PP -document.browse.forms.editor (default: "") +document.browse.forms.editor \fB\fR (default: "") .RS 4 Path to the executable that -\fIELinks\fR +ELinks should launch when the user requests to edit a textarea with an external editor. If this is blank, -\fIELinks\fR -will use the value of the environmental variable $EDITOR. If $EDITOR is empty or not set, -\fIELinks\fR -will then default to "vi". +ELinks +will use the value of the environmental variable +\fB$EDITOR\fR. If +\fB$EDITOR\fR +is empty or not set, +ELinks +will then default to +\fBvi\fR. .RE .PP -document.browse.forms.show_formhist [0|1] (default: 0) +document.browse.forms.show_formhist \fB[0|1]\fR (default: 0) .RS 4 Ask if a login form should be saved to file or not. This option only disables the dialog, already saved login forms are unaffected. .RE -.PP -document.browse.images -.RS 4 +.SS "document.browse.images (Images)" Options for handling of images. -.RE +.sp .PP -document.browse.images.display_style (default: 2) +document.browse.images.display_style \fB\fR (default: 2) .RS 4 Display style for image tags when displayed: .sp .RS 4 -\h'-04'\(bu\h'+03'0: means always display IMG +\h'-04'\(bu\h'+03'0 means always display +IMG .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: means always display filename +\h'-04'\(bu\h'+03'1 means always display filename .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: means display alt/title attribute if possible, IMG if not +\h'-04'\(bu\h'+03'2 means display +alt/title +attribute if possible, +IMG +if not .RE .sp .RS 4 -\h'-04'\(bu\h'+03'3: means display alt/title attribute if possible, filename if not +\h'-04'\(bu\h'+03'3 means display +alt/title +attribute if possible, filename if not .RE .RE .PP -document.browse.images.filename_maxlen (default: 0) +document.browse.images.filename_maxlen \fB\fR (default: 0) .RS 4 Maximum length of image filename when displayed: .sp .RS 4 -\h'-04'\(bu\h'+03'0: means always display full filename +\h'-04'\(bu\h'+03'0 means always display full filename .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1\-500: means display filename with this maximal length; if it is longer, the middle is substituted by an asterisk +\h'-04'\(bu\h'+03'1\-500 means display filename with this maximal length; if it is longer, the middle is substituted by an asterisk .RE .RE .PP -document.browse.images.image_link_tagging (default: 1) +document.browse.images.image_link_tagging \fB\fR (default: 1) .RS 4 When to enclose image links: .sp .RS 4 -\h'-04'\(bu\h'+03'0: means never +\h'-04'\(bu\h'+03'0 means never .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: means never if alt or title are provided (old behavior) +\h'-04'\(bu\h'+03'1 means never if alt or title are provided (old behavior) .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: means always +\h'-04'\(bu\h'+03'2 means always .RE .RE .PP -document.browse.images.image_link_prefix (default: "[") +document.browse.images.image_link_prefix \fB\fR (default: "[") .RS 4 Prefix string to use to mark image links. .RE .PP -document.browse.images.image_link_suffix (default: "]") +document.browse.images.image_link_suffix \fB\fR (default: "]") .RS 4 Suffix string to use to mark image links. .RE .PP -document.browse.images.label_maxlen (default: 0) +document.browse.images.label_maxlen \fB\fR (default: 0) .RS 4 Maximum length of image label (alt/title): .sp .RS 4 -\h'-04'\(bu\h'+03'0: means always display full label +\h'-04'\(bu\h'+03'0 means always display full label .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1\-500: means display label with this maximal length; if it is longer, the middle is substituted by an asterisk +\h'-04'\(bu\h'+03'1\-500 means display label with this maximal length; if it is longer, the middle is substituted by an asterisk .RE .RE .PP -document.browse.images.show_as_links [0|1] (default: 0) +document.browse.images.show_as_links \fB[0|1]\fR (default: 0) .RS 4 -Display links to images without an alt attribute. If this option is off, these images are completely invisible. +Display links to images without an +alt +attribute. If this option is off, these images are completely invisible. .RE .PP -document.browse.images.show_any_as_links [0|1] (default: 1) +document.browse.images.show_any_as_links \fB[0|1]\fR (default: 1) .RS 4 -Display links to any images in the document, regardless of them having an alt attribute or not. If this option is off, the alt attribute contents is shown, but as normal text, not selectable as a link. +Display links to any images in the document, regardless of them having an +alt +attribute or not. If this option is off, the alt attribute contents is shown, but as normal text, not selectable as a link. .RE -.PP -document.browse.links -.RS 4 +.SS "document.browse.links (Links)" Options for handling of links to other documents. -.RE +.sp .PP -document.browse.links.color_dirs [0|1] (default: 1) +document.browse.links.color_dirs \fB[0|1]\fR (default: 1) .RS 4 Highlight links to directories in FTP and local directory listing. .RE .PP -document.browse.links.numbering [0|1] (default: 0) +document.browse.links.numbering \fB[0|1]\fR (default: 0) .RS 4 Display numbers next to the links. .RE .PP -document.browse.links.target_blank (default: 0) +document.browse.links.target_blank \fB\fR (default: 0) .RS 4 Define how to handle links having target=_blank set: .sp .RS 4 -\h'-04'\(bu\h'+03'0: means open link in current tab +\h'-04'\(bu\h'+03'0 means open link in current tab .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: means open link in new tab in foreground +\h'-04'\(bu\h'+03'1 means open link in new tab in foreground .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: means open link in new tab in background +\h'-04'\(bu\h'+03'2 means open link in new tab in background .RE .sp .RS 4 -\h'-04'\(bu\h'+03'3: means open link in new window +\h'-04'\(bu\h'+03'3 means open link in new window .RE .RE .PP -document.browse.links.use_tabindex [0|1] (default: 1) +document.browse.links.use_tabindex \fB[0|1]\fR (default: 1) .RS 4 -Whether to navigate links using tabindex specified ordering. The TABINDEX attribute in HTML elements specifies the order in which links should receive focus when using the keyboard to navigate the document. +Whether to navigate links using tabindex specified ordering. The +TABINDEX +attribute in HTML elements specifies the order in which links should receive focus when using the keyboard to navigate the document. .RE .PP -document.browse.links.missing_fragment [0|1] (default: 1) +document.browse.links.missing_fragment \fB[0|1]\fR (default: 1) .RS 4 Open a message box when document has no tag with given id. .RE .PP -document.browse.links.number_keys_select_link (default: 1) +document.browse.links.number_keys_select_link \fB\fR (default: 1) .RS 4 Number keys select links rather than specify command prefixes. This is a tristate: .sp .RS 4 -\h'-04'\(bu\h'+03'0: means never +\h'-04'\(bu\h'+03'0 means never .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: means if document.browse.links.numbering = 1 +\h'-04'\(bu\h'+03'1 means if document.browse.links.numbering = 1 .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: means always +\h'-04'\(bu\h'+03'2 means always .RE .RE .PP -document.browse.links.warn_malicious [0|1] (default: 1) +document.browse.links.warn_malicious \fB[0|1]\fR (default: 1) .RS 4 When following a link the user ID part of the URI is checked and if a maliciously crafted URI is detected a warning dialog will ask before following the link. .RE .PP -document.browse.links.wraparound [0|1] (default: 0) +document.browse.links.wraparound \fB[0|1]\fR (default: 0) .RS 4 When pressing 'down' on the last link, jump to the first one, and vice versa. .RE -.PP -document.browse.links.active_link -.RS 4 +.SS "document.browse.links.active_link (Active link)" Options for the active link. -.RE +.sp .PP -document.browse.links.active_link.enable_color [0|1] (default: 0) +document.browse.links.active_link.enable_color \fB[0|1]\fR (default: 0) .RS 4 Enable use of the active link background and text color settings instead of the link colors from the document. .RE .PP -document.browse.links.active_link.bold [0|1] (default: 0) +document.browse.links.active_link.bold \fB[0|1]\fR (default: 0) .RS 4 Make the active link text bold. .RE .PP -document.browse.links.active_link.invert [0|1] (default: 1) +document.browse.links.active_link.invert \fB[0|1]\fR (default: 1) .RS 4 Invert the fore\- and background color so the link stands out. .RE .PP -document.browse.links.active_link.underline [0|1] (default: 0) +document.browse.links.active_link.underline \fB[0|1]\fR (default: 0) .RS 4 Underline the active link. .RE -.PP -document.browse.links.active_link.colors -.RS 4 +.SS "document.browse.links.active_link.colors (Colors)" Active link colors. -.RE +.sp .PP -document.browse.links.active_link.colors.background (default: blue) +document.browse.links.active_link.colors.background \fB\fR (default: blue) .RS 4 Default background color. .RE .PP -document.browse.links.active_link.colors.text (default: black) +document.browse.links.active_link.colors.text \fB\fR (default: black) .RS 4 Default text color. .RE -.PP -document.browse.scrolling -.RS 4 +.SS "document.browse.scrolling (Scrolling)" Scrolling options. -.RE +.sp .PP -document.browse.scrolling.horizontal_extended [0|1] (default: 1) +document.browse.scrolling.horizontal_extended \fB[0|1]\fR (default: 1) .RS 4 Whether to allow horizontal scrolling when the document does not extend off the screen. Useful for copy/paste operations. .RE .PP -document.browse.scrolling.horizontal_step (default: 8) +document.browse.scrolling.horizontal_step \fB\fR (default: 8) .RS 4 Number of columns to scroll when a key bound to scroll\-left or scroll\- right is pressed and no prefix was given. .RE .PP -document.browse.scrolling.margin (default: 3) +document.browse.scrolling.margin \fB\fR (default: 3) .RS 4 -Size of the virtual margin \- when you click inside of that margin, document scrolls in that direction. +Size of the virtual margin \(en when you click inside of that margin, document scrolls in that direction. .RE .PP -document.browse.scrolling.vertical_step (default: 2) +document.browse.scrolling.vertical_step \fB\fR (default: 2) .RS 4 Number of lines to scroll when a key bound to scroll\-up or scroll\- down is pressed and no prefix was given. .RE -.PP -document.browse.search -.RS 4 +.SS "document.browse.search (Searching)" Options for searching. -.RE +.sp .PP -document.browse.search.case [0|1] (default: 0) +document.browse.search.case \fB[0|1]\fR (default: 0) .RS 4 Whether the search should match the document text while maintaining case sensitivity. .RE .PP -document.browse.search.regex (default: 0) +document.browse.search.regex \fB\fR (default: 0) .RS 4 Enable searching with regular expressions: .sp .RS 4 -\h'-04'\(bu\h'+03'0: for plain text searching +\h'-04'\(bu\h'+03'0 for plain text searching .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: for basic regular expression searches +\h'-04'\(bu\h'+03'1 for basic regular expression searches .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: for extended regular expression searches +\h'-04'\(bu\h'+03'2 for extended regular expression searches .RE .RE .PP -document.browse.search.show_hit_top_bottom [0|1] (default: 1) +document.browse.search.show_hit_top_bottom \fB[0|1]\fR (default: 1) .RS 4 Whether to show a dialog when the search hits the top or bottom of the document. .RE .PP -document.browse.search.wraparound [0|1] (default: 1) +document.browse.search.wraparound \fB[0|1]\fR (default: 1) .RS 4 Wrap around when searching. Currently only used for typeahead. .RE .PP -document.browse.search.show_not_found (default: 2) +document.browse.search.show_not_found \fB\fR (default: 2) .RS 4 How to inform the user when nothing is matched: .sp .RS 4 -\h'-04'\(bu\h'+03'0: means do nothing +\h'-04'\(bu\h'+03'0 means do nothing .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: means beep the terminal +\h'-04'\(bu\h'+03'1 means beep the terminal .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: means pop up message box +\h'-04'\(bu\h'+03'2 means pop up message box .RE .RE .PP -document.browse.search.typeahead (default: 0) +document.browse.search.typeahead \fB\fR (default: 0) .RS 4 Start typeahead searching when an unbound key is pressed without any modifiers. Note that most keys have default bindings, so this feature will not be useful unless you unbind them. .sp .RS 4 -\h'-04'\(bu\h'+03'0: disables this feature; typeahead searching will only be used when you press a key bound to search\-typeahead or similar +\h'-04'\(bu\h'+03'0 disables this feature; typeahead searching will only be used when you press a key bound to search\-typeahead or similar .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: automatically starts typeahead searching thru link text +\h'-04'\(bu\h'+03'1 automatically starts typeahead searching thru link text .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: automatically starts typeahead searching thru all document text +\h'-04'\(bu\h'+03'2 automatically starts typeahead searching thru all document text .RE .RE -.PP -document.cache -.RS 4 +.SS "document.cache (Cache)" Cache options. -.RE +.sp .PP -document.cache.cache_redirects [0|1] (default: 0) +document.cache.cache_redirects \fB[0|1]\fR (default: 0) .RS 4 -Cache even redirects sent by server (usually thru HTTP by a 302 HTTP code and a Location header). This was the original behaviour for quite some time, but it causes problems in a situation very common to various web login systems \- frequently, when accessing a certain location, they will redirect you to a login page if they don't receive an auth cookie, the login page then gives you the cookie and redirects you back to the original page, but there you have already cached redirect back to the login page! If this option has value of 0, this malfunction is fixed, but occasionally you may get superfluous (depends on how you take it ;\-) requests to the server. If this option has value of 1, experienced users can still workaround it by clever combination of usage of reload, jumping around in session history and hitting ctrl+enter. Note that this option is checked when retrieving the information from cache, not when saving it to cache \- thus if you enable it, even previous redirects will be taken from cache instead of asking the server. +Cache even redirects sent by server (usually thru HTTP by a 302 HTTP code and a Location header). This was the original behaviour for quite some time, but it causes problems in a situation very common to various web login systems \(en frequently, when accessing a certain location, they will redirect you to a login page if they don't receive an auth cookie, the login page then gives you the cookie and redirects you back to the original page, but there you have already cached redirect back to the login page! If this option has value of 0, this malfunction is fixed, but occasionally you may get superfluous (depends on how you take it ;\-) requests to the server. If this option has value of 1, experienced users can still workaround it by clever combination of usage of reload, jumping around in session history and hitting ctrl+enter. Note that this option is checked when retrieving the information from cache, not when saving it to cache \(en thus if you enable it, even previous redirects will be taken from cache instead of asking the server. .RE .PP -document.cache.ignore_cache_control [0|1] (default: 1) +document.cache.ignore_cache_control \fB[0|1]\fR (default: 1) .RS 4 Ignore Cache\-Control and Pragma server headers. When set, the document is cached even with 'Cache\-Control: no\-cache'. .RE .PP -document.cache.revalidation_interval (default: \-1) +document.cache.revalidation_interval \fB\fR (default: \-1) .RS 4 Period in seconds that a cache entry is considered to be up\-to\-date. When a document is loaded and this interval has elapsed since the document was initially loaded or most recently revalidated with the server, the server will be checked in case there is a more up\-to\-date version of the document. .sp A value of \-1 disables automatic revalidation. .RE -.PP -document.cache.format -.RS 4 +.SS "document.cache.format (Formatted documents)" Format cache options. -.RE +.sp .PP -document.cache.format.size (default: 5) +document.cache.format.size \fB\fR (default: 5) .RS 4 -Number of cached formatted pages. Do not get too generous here, 'formatted' means that all the accompanying structures are kept in memory so that you get the cached document immediatelly, but these structures may take a lot \- 2x the size of the HTML source is probably not unusual, but it can be even more if the document consists of a lot of short lines (padded right, if possible) and links and not much other markup. So if you set this to 256 and then you don't like your -\fIELinks\fR +Number of cached formatted pages. Do not get too generous here, 'formatted' means that all the accompanying structures are kept in memory so that you get the cached document immediatelly, but these structures may take a lot \(en 2x the size of the HTML source is probably not unusual, but it can be even more if the document consists of a lot of short lines (padded right, if possible) and links and not much other markup. So if you set this to 256 and then you don't like your +ELinks eating 90M, don't come complaining to us. ;\-) Also note that the format cache itself is not counted to the memory cache size, but the HTML source of the formatted documents is always cached, even if it is over the memory cache size threshold. (Then of course no other documents can be cached.) .RE -.PP -document.cache.memory -.RS 4 +.SS "document.cache.memory (Memory cache)" Memory cache options. -.RE +.sp .PP -document.cache.memory.size (default: 1048576) +document.cache.memory.size \fB\fR (default: 1048576) .RS 4 Memory cache size (in bytes). .RE -.PP -document.codepage -.RS 4 +.SS "document.codepage (Charset)" Charset options. -.RE +.sp .PP -document.codepage.assume (default: System) +document.codepage.assume \fB\fR (default: System) .RS 4 Default document codepage. 'System' stands for a codepage determined by a selected locale. .RE .PP -document.codepage.force_assumed [0|1] (default: 0) +document.codepage.force_assumed \fB[0|1]\fR (default: 0) .RS 4 Ignore charset info sent by server. .RE -.PP -document.colors -.RS 4 +.SS "document.colors (Default color settings)" Default document color settings. -.RE +.sp .PP -document.colors.text (default: gray75) +document.colors.text \fB\fR (default: gray75) .RS 4 Default text color. .RE .PP -document.colors.background (default: black) +document.colors.background \fB\fR (default: black) .RS 4 Default background color. .RE .PP -document.colors.link (default: blue) +document.colors.link \fB\fR (default: blue) .RS 4 Default link color. .RE .PP -document.colors.vlink (default: yellow) +document.colors.vlink \fB\fR (default: yellow) .RS 4 Default visited link color. .RE .PP -document.colors.image (default: darkolivegreen) +document.colors.image \fB\fR (default: darkolivegreen) .RS 4 Default image link color. .RE .PP -document.colors.bookmark (default: hotpink) +document.colors.bookmark \fB\fR (default: hotpink) .RS 4 Default bookmarked link color. .RE .PP -document.colors.dirs (default: yellow) +document.colors.dirs \fB\fR (default: yellow) .RS 4 -Default directory color. See document.browse.links.color_dirs option. +Default directory color. See +document.browse.links.color_dirs +option. .RE .PP -document.colors.increase_contrast [0|1] (default: 1) +document.colors.increase_contrast \fB[0|1]\fR (default: 1) .RS 4 Increase the contrast between the foreground and background colors to ensure readability. For example it disallows dark colors on a black background. Note, this is different from ensuring the contrast with the ensure_contrast option. .RE .PP -document.colors.ensure_contrast [0|1] (default: 1) +document.colors.ensure_contrast \fB[0|1]\fR (default: 1) .RS 4 Makes sure that the back\- and foreground colors are never equal. .RE .PP -document.colors.use_document_colors (default: 2) +document.colors.use_document_colors \fB\fR (default: 2) .RS 4 Use colors specified in document: .sp .RS 4 -\h'-04'\(bu\h'+03'0: is use always the default settings +\h'-04'\(bu\h'+03'0 is use always the default settings .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: is use document colors if available, except background +\h'-04'\(bu\h'+03'1 is use document colors if available, except background .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: is use document colors, including background. This can mostly look very impressive, but some sites will appear really ugly. Note, that obviously if the background is not black, it will break the behaviour of transparency. +\h'-04'\(bu\h'+03'2 is use document colors, including background. This can mostly look very impressive, but some sites will appear really ugly. Note, that obviously if the background is not black, it will break the behaviour of transparency. .RE .RE -.PP -document.css -.RS 4 +.SS "document.css (Cascading Style Sheets)" Options concerning how to use CSS for styling documents. -.RE +.sp .PP -document.css.enable [0|1] (default: 1) +document.css.enable \fB[0|1]\fR (default: 1) .RS 4 Enable adding of CSS style info to documents. .RE .PP -document.css.import [0|1] (default: 1) +document.css.import \fB[0|1]\fR (default: 1) .RS 4 When enabled any external style sheets that are imported from either CSS itself using the @import keyword or from the HTML using tags in the document header will also be downloaded. .RE .PP -document.css.stylesheet (default: "") +document.css.stylesheet \fB\fR (default: "") .RS 4 The path to the file containing the default user defined Cascading Style Sheet. It can be used to control the basic layout of HTML documents. The path is assumed to be relative to -\fIELinks\fR' home directory. Leave as "" to use built\-in document styling. +ELinks' home directory. Leave as "" to use built\-in document styling. .RE -.PP -document.download -.RS 4 +.SS "document.download (Downloading)" Options regarding files downloading and handling. -.RE +.sp .PP -document.download.directory (default: "./") +document.download.directory \fB\fR (default: "./") .RS 4 Default download directory. .RE .PP -document.download.set_original_time [0|1] (default: 0) +document.download.set_original_time \fB[0|1]\fR (default: 0) .RS 4 Set the timestamp of each downloaded file to the timestamp stored on the server. .RE .PP -document.download.overwrite (default: 2) +document.download.overwrite \fB\fR (default: 2) .RS 4 Prevent overwriting the local files: .sp .RS 4 -\h'-04'\(bu\h'+03'0: is files will silently be overwritten +\h'-04'\(bu\h'+03'0 is files will silently be overwritten .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: is add a suffix .{number} (for example '.1') to the name +\h'-04'\(bu\h'+03'1 is add a suffix .{number} (for example '.1') to the name .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: is ask the user +\h'-04'\(bu\h'+03'2 is ask the user .RE .RE .PP -document.download.notify_bell (default: 0) +document.download.notify_bell \fB\fR (default: 0) .RS 4 Audio notification when download is completed: .sp .RS 4 -\h'-04'\(bu\h'+03'0: is never +\h'-04'\(bu\h'+03'0 is never .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: is when background notification is active +\h'-04'\(bu\h'+03'1 is when background notification is active .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: is always +\h'-04'\(bu\h'+03'2 is always .RE .RE -.PP -document.dump -.RS 4 +.SS "document.dump (Dump output)" Dump output options. -.RE +.sp .PP -document.dump.codepage (default: System) +document.dump.codepage \fB\fR (default: System) .RS 4 Codepage used in dump output. 'System' stands for a codepage determined by a selected locale. .RE .PP -document.dump.color_mode (default: \-1) +document.dump.color_mode \fB\fR (default: \-1) .RS 4 -Color mode for dumps. Some modes may have been disabled at compile time. The Setup \-> Terminal options dialog lists the modes supported by this executable. If you select an unsupported mode, -\fIELinks\fR +Color mode for dumps. Some modes may have been disabled at compile time. The +Setup \(-> Terminal options +dialog lists the modes supported by this executable. If you select an unsupported mode, +ELinks uses 16 colors. The color modes are: .sp .RS 4 -\h'-04'\(bu\h'+03'\-1: is standard dump mode +\h'-04'\(bu\h'+03'\-1 is standard dump mode .RE .sp .RS 4 -\h'-04'\(bu\h'+03'0: is mono mode +\h'-04'\(bu\h'+03'0 is mono mode .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: is 16 color mode +\h'-04'\(bu\h'+03'1 is 16 color mode .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: is 88 color mode +\h'-04'\(bu\h'+03'2 is 88 color mode .RE .sp .RS 4 -\h'-04'\(bu\h'+03'3: is 256 color mode +\h'-04'\(bu\h'+03'3 is 256 color mode .RE .sp .RS 4 -\h'-04'\(bu\h'+03'4: is true color mode +\h'-04'\(bu\h'+03'4 is true color mode .RE .RE .PP -document.dump.footer (default: "") +document.dump.footer \fB\fR (default: "") .RS 4 Footer string used in dumps. %u is substituted by URL. .RE .PP -document.dump.header (default: "") +document.dump.header \fB\fR (default: "") .RS 4 Header string used in dumps. %u is substituted by URL. .RE .PP -document.dump.numbering [0|1] (default: 1) +document.dump.numbering \fB[0|1]\fR (default: 1) .RS 4 Whether to print link numbers in dump output. .RE .PP -document.dump.references [0|1] (default: 1) +document.dump.references \fB[0|1]\fR (default: 1) .RS 4 Whether to print references (URIs) of document links in dump output. .RE .PP -document.dump.separator (default: " +document.dump.separator \fB\fR (default: " ") .RS 4 String which separates two dumps. .RE .PP -document.dump.width (default: 80) +document.dump.width \fB\fR (default: 80) .RS 4 Width of screen in characters when dumping documents. .RE -.PP -document.history -.RS 4 +.SS "document.history (History)" History options. -.RE +.sp .PP -document.history.keep_unhistory [0|1] (default: 1) +document.history.keep_unhistory \fB[0|1]\fR (default: 1) .RS 4 Keep unhistory ("forward history"). .RE -.PP -document.history.global -.RS 4 +.SS "document.history.global (Global history)" Global history options. -.RE +.sp .PP -document.history.global.enable [0|1] (default: 1) +document.history.global.enable \fB[0|1]\fR (default: 1) .RS 4 Enable global history ("history of all pages visited"). .RE .PP -document.history.global.max_items (default: 1024) +document.history.global.max_items \fB\fR (default: 1024) .RS 4 Maximum number of entries in the global history. .RE .PP -document.history.global.display_type (default: 0) +document.history.global.display_type \fB\fR (default: 0) .RS 4 What to display in global history dialog: .sp .RS 4 -\h'-04'\(bu\h'+03'0: is URLs +\h'-04'\(bu\h'+03'0 is URLs .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: is page titles +\h'-04'\(bu\h'+03'1 is page titles .RE .RE -.PP -document.html -.RS 4 +.SS "document.html (HTML rendering)" Options concerning the display of HTML pages. -.RE +.sp .PP -document.html.display_frames [0|1] (default: 1) +document.html.display_frames \fB[0|1]\fR (default: 1) .RS 4 Display frames. .RE .PP -document.html.display_tables [0|1] (default: 1) +document.html.display_tables \fB[0|1]\fR (default: 1) .RS 4 Display tables. .RE .PP -document.html.display_subs [0|1] (default: 1) +document.html.display_subs \fB[0|1]\fR (default: 1) .RS 4 Display subscripts (as [thing]). .RE .PP -document.html.display_sups [0|1] (default: 1) +document.html.display_sups \fB[0|1]\fR (default: 1) .RS 4 Display superscripts (as ^thing). .RE .PP -document.html.link_display (default: 2) +document.html.link_display \fB\fR (default: 2) .RS 4 How to render tags from the HTML header: .sp .RS 4 -\h'-04'\(bu\h'+03'0: is nothing +\h'-04'\(bu\h'+03'0 is nothing .RE .sp .RS 4 -\h'-04'\(bu\h'+03'1: is title +\h'-04'\(bu\h'+03'1 is title .RE .sp .RS 4 -\h'-04'\(bu\h'+03'2: is name in addition +\h'-04'\(bu\h'+03'2 is name in addition .RE .sp .RS 4 -\h'-04'\(bu\h'+03'3: is hreflang in addition +\h'-04'\(bu\h'+03'3 is hreflang in addition .RE .sp .RS 4 -\h'-04'\(bu\h'+03'4: is type in addition +\h'-04'\(bu\h'+03'4 is type in addition .RE .sp .RS 4 -\h'-04'\(bu\h'+03'5: is everything +\h'-04'\(bu\h'+03'5 is everything .RE .RE .PP -document.html.underline_links [0|1] (default: 0) +document.html.underline_links \fB[0|1]\fR (default: 0) .RS 4 Underline links. .RE .PP -document.html.wrap_nbsp [0|1] (default: 0) +document.html.wrap_nbsp \fB[0|1]\fR (default: 0) .RS 4 If set do not honour non breaking space (the nbsp entity) but allow to wrap the text. This can help keeping the width of documents down so no horizontal scrolling is needed. .RE -.PP -document.plain -.RS 4 +.SS "document.plain (Plain rendering)" Options concerning the display of plain text pages. -.RE +.sp .PP -document.plain.display_links [0|1] (default: 0) +document.plain.display_links \fB[0|1]\fR (default: 0) .RS 4 Display URIs in the document as links. .RE .PP -document.plain.compress_empty_lines [0|1] (default: 0) +document.plain.compress_empty_lines \fB[0|1]\fR (default: 0) .RS 4 Compress successive empty lines to only one in displayed text. .RE -.PP -document.uri_passing -.RS 4 +.SS "document.uri_passing (URI passing)" Rules for passing URIs to external commands. When one rule is defined the link and tab menu will have a menu item that makes it possible to pass the the link, frame or tab URI to an external command. If several rules are defined the link and tab menu will have a submenu of items for each rule. Note, this is mostly useful for launching graphical viewers, since there is no support for releasing the terminal while the command runs. The action and submenus are also available by binding keys to the frame\-external\-command, the link\-external\-command, and the tab\-external\-command actions. -.RE +.sp .PP -document.uri_passing._template_ (default: "") +document.uri_passing._template_ \fB\fR (default: "") .RS 4 -A rule for passing URI to an external command. The format is: %c in the string means the current URL %% in the string means '%' Do _not_ put single\- or double\-quotes around %c. +A rule for passing URI to an external command. The format is: +.sp +.RS 4 +\h'-04'\(bu\h'+03'%c in the string means the current URL .RE -.PP -ecmascript +.sp .RS 4 +\h'-04'\(bu\h'+03'%% in the string means '%' +.RE +.IP "" 4 +Do +\fBnot\fR +put single\- or double\-quotes around %c. +.RE +.SS "ecmascript (ECMAScript)" ECMAScript options. -.RE +.sp .PP -ecmascript.enable [0|1] (default: 0) +ecmascript.enable \fB[0|1]\fR (default: 0) .RS 4 Whether to run those scripts inside of documents. .RE .PP -ecmascript.error_reporting [0|1] (default: 0) +ecmascript.error_reporting \fB[0|1]\fR (default: 0) .RS 4 Open a message box when a script reports an error. .RE .PP -ecmascript.ignore_noscript [0|1] (default: 0) +ecmascript.ignore_noscript \fB[0|1]\fR (default: 0) .RS 4 Whether to ignore content enclosed by the