From kon at iki.fi  Sat Mar  1 11:00:19 2008
From: kon at iki.fi (Kalle Olavi Niemitalo)
Date: Sat, 01 Mar 2008 20:00:19 +0200
Subject: [elinks-dev] line wrapping in option descriptions
Message-ID: <87d4qe5npo.fsf@Astalo.kon.iki.fi>

ELinks source code defines options like this:

	INIT_OPT_BOOL("protocol.http", N_("Use UI language as Accept-Language"),
		"accept_ui_language", 0, 1,
		N_("Request localised versions of documents from web-servers (using the\n"
		"Accept-Language header) using the language you have configured for\n"
		"ELinks' user-interface (this also affects navigator.language ECMAScript\n"
		"value available to scripts). Note that some see this as a potential\n"
		"security risk because it tells web-masters and the FBI sniffers about\n"
		"your language preference.")),

In the description of this option, the longest line is 71
characters.  However, when ELinks runs on a 80-column terminal,
with the standard src/setup.h, it apparently wraps option
descriptions to 60 columns.  The description then looks a bit
silly and consumes more vertical space than necessary:

|  Request localised versions of documents from web-servers      |
|  (using the                                                    |
|  Accept-Language header) using the language you have           |
|  configured for                                                |
|  ELinks' user-interface (this also affects navigator.language  |
|  ECMAScript                                                    |
|  value available to scripts). Note that some see this as a     |
|  potential                                                     |
|  security risk because it tells web-masters and the FBI        |
|  sniffers about                                                |
|  your language preference.                                     |
 
I propose we change most newlines to spaces in the option.desc strings:

	INIT_OPT_BOOL("protocol.http", N_("Use UI language as Accept-Language"),
		"accept_ui_language", 0, 1,
		N_("Request localised versions of documents from web-servers (using the "
		"Accept-Language header) using the language you have configured for "
		"ELinks' user-interface (this also affects navigator.language ECMAScript "
		"value available to scripts). Note that some see this as a potential "
		"security risk because it tells web-masters and the FBI sniffers about "
		"your language preference.")),

Of course, newlines that delimit paragraphs or list items would
be left in.  Then, the description would instead look like this:

|  Request localised versions of documents from web-servers      |
|  (using the Accept-Language header) using the language you     |
|  have configured for ELinks' user-interface (this also         |
|  affects navigator.language ECMAScript value available to      |
|  scripts). Note that some see this as a potential security     |
|  risk because it tells web-masters and the FBI sniffers about  |
|  your language preference.                                     |

This change would require rewriting the translations in po/
though, so I don't know whether it is appropriate for 0.12.GIT.
Currently, 0.12.GIT and 0.11.4rc0.GIT are very compatible with
respect to po files, and this in principle allows 0.11.* to
benefit from po/perl/msgaccel-check in 0.12.GIT.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 188 bytes
Desc: not available
Url : http://linuxfromscratch.org/pipermail/elinks-dev/attachments/20080301/eda08dd9/attachment.bin 

From fonseca at diku.dk  Sat Mar  1 12:16:07 2008
From: fonseca at diku.dk (Jonas Fonseca)
Date: Sat, 1 Mar 2008 20:16:07 +0100
Subject: [elinks-dev] line wrapping in option descriptions
In-Reply-To: <87d4qe5npo.fsf@Astalo.kon.iki.fi>
References: <87d4qe5npo.fsf@Astalo.kon.iki.fi>
Message-ID: <20080301191607.GA30561@diku.dk>

Kalle Olavi Niemitalo <kon at iki.fi> wrote Sat, Mar 01, 2008:
> I propose we change most newlines to spaces in the option.desc strings:
>
> [snip example]
> 
> Of course, newlines that delimit paragraphs or list items would
> be left in.

I know that witekfl tried to push for this change and even did some work
on this.

> This change would require rewriting the translations in po/
> though, so I don't know whether it is appropriate for 0.12.GIT.

Did you investigate whether we can simply replace the newlines with
spaces in the po files and things will work?

> Currently, 0.12.GIT and 0.11.4rc0.GIT are very compatible with
> respect to po files, and this in principle allows 0.11.* to
> benefit from po/perl/msgaccel-check in 0.12.GIT.

I am not expecting a lot of new 0.11.* releases, so I don't think the po
compatibility argument should hold back this thing from entering 0.12.

The bigger question to me is what will happen with 0.12 and beyond? As
you and other developers have noticed I am not much active anymore, and
when I am, it mostly amounts to a few documentation and website updates.
Lacking a real maintainer, does it make sense to have anything other
than a "current" branch?

In my opinion and in my perhaps more current role as merely a release
manager, it seems like a simpler solution. We can have some monthly or
quarterly "elinks-%Y.%m" release, possibly with a "-quirky" or "-dev"
tag attached to warn. This way upgrade pain is amortized better, users
are happy, and developers full of hope! I think this development model
fits better the slower development pace ELinks is in, besides I have
always felt that the development branch has been pretty stable.

-- 
Jonas Fonseca

From kon at iki.fi  Fri Mar  7 16:44:11 2008
From: kon at iki.fi (Kalle Olavi Niemitalo)
Date: Sat, 08 Mar 2008 01:44:11 +0200
Subject: [elinks-dev] doc/tools/help2doc rewrite in Perl
Message-ID: <87d4q6gkvo.fsf@Astalo.kon.iki.fi>

Here is a Perl version of doc/tools/help2doc.
The shell version takes 1 min 33 s but this takes only 0.30 s.
It generates an identical option-command.txt but fixes several bugs
in option-config.txt, as you can see from the included diff.
document.dump.separator is still not entirely right though.

OK to apply?  If not, please fix the shell version.

======================================================================

#! /usr/bin/perl
use strict;
use warnings;

my ($elinks, $option) = @ARGV;

if ($option =~ /command/) {
    open my $pipe, "-|", $elinks, "--long-help" or die;
    my $version = <$pipe>;
    chomp $version;
    $version =~ s/^ELinks ([-.\w]+).*$/$1/ or die "unusual version: $version";
    my $blank = 1;
    while (<$pipe>) {
	if (/^ {4}(-.*?) *$/) {
	    $_ = $1;
	    s/ {2,}/ /g;
	    print "${_}::\n";
	} elsif (/^ {12}\t(-eval .*)$/) {
	    print "\n\t$1\n";
	} elsif (/^ {12}\t(\w+\(.*\)) +: (.*)$/) {
	    print "\t- `$1`: $2\n";
	} elsif (/^ {12}\t(\d+) (means .+)$/) {
	    print "\t- $1:\t$2\n";
	} elsif (s/^ {12}//) {
	    s/'([^']+)'/\\'$1\\'/g;
	    s((~/\.elinks|-dump|-default-mime-type|text/html|-touch-files|-no-connect|-session-ring))(`$1`)g;
	    s/(ELinks|HOME)/'$1'/g;
	    print "\t$_";
	} else {
	    print "\n" unless $blank;
	    $blank = 2;
	}
	$blank = ($blank == 2);
    }
    print "Generated using output from ELinks version $version.\n";
} elsif ($option =~ /config/) {
    open my $pipe, "-|", $elinks, "--config-help" or die;
    my $version = <$pipe>;
    chomp $version;
    $version =~ s/^ELinks ([-.\w]+).*$/$1/ or die "unusual version: $version";
    my $blank = 1;
    while (<$pipe>) {
	if (/^ {2}[^ ].*: \(([-.\w]+)\)$/) {
	    print "$1::\n";
	} elsif (/^ {4}([^ ].*?)$/) {
	    print "$1::\n";
	} elsif (s/^ {12,}//) {
	    # escape things that might look like AsciiDoc markup
	    s/'(.*?)'/\\'$1\\'/g;
	    s/\{(.*?)\}/\\{$1\\}/g;
	    # add the actual AsciiDoc markup
	    s/(ELinks|WWW_HOME)/'$1'/g;
	    s((~/\.elinks))(`$1`)g;
	    if (/^(-?\d[-+\d]*?) +(.*)$/) {
		print "\t- $1:\t$2\n";
	    } else {
		print "\t$_";
	    }
	} else {
	    print "\n" unless $blank;
	    $blank = 2;
	}
	$blank = ($blank == 2);
    }
    print "Generated using output from ELinks version $version.\n";
} else {
    die "you rang?";
}

======================================================================

--- option-config-old.txt	2008-03-08 01:28:40.000000000 +0200
+++ option-config-new.txt	2008-03-08 01:29:05.000000000 +0200
@@ -124,7 +124,7 @@
 	- -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
+	- 1+:	is use cookie's expiration date, but limit age to the given
 	number of days
 
 cookies.paranoid_security [0|1] (default: 0)::
@@ -360,10 +360,11 @@
 	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.
-
-when you (when you press a key bound to search-typeahead or similar)::
-	1 automatically starts typeahead searching thru link text
-	2 automatically starts typeahead searching thru all document text
+	
+	- 0:	disables this feature; typeahead searching will only be used
+	when you press a key bound to search-typeahead or similar
+	- 1:	automatically starts typeahead searching thru link text
+	- 2:	automatically starts typeahead searching thru all document text
 
 document.browse.margin_width <num> (default: 3)::
 	Horizontal text margin.
@@ -441,6 +442,8 @@
 	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.
+	
+	A value of -1 disables automatic revalidation.
 
 document.codepage::
 	Charset options.
@@ -514,8 +517,8 @@
 
 document.css.media <str> (default: "tty")::
 	CSS media types that 'ELinks' claims to support, separated with
-	commas. The "all" type is implied. Currently, only ASCII
-	characters work reliably here. See CSS2 section 7:
+	commas.  The "all" type is implied.  Currently, only ASCII
+	characters work reliably here.  See CSS2 section 7:
 	http://www.w3.org/TR/1998/REC-CSS2-19980512/media.html
 
 document.css.stylesheet <str> (default: "")::
@@ -578,7 +581,9 @@
 	Whether to print references (URIs) of document links
 	in dump output.
 
-document.dump.separator <str> (document.dump.separator <str> (default: ")::
+document.dump.separator <str> (default: "::
+
+	String which separates two dumps.
 
 document.dump.width <num> (default: 80)::
 	Width of screen in characters when dumping documents.
@@ -926,7 +931,7 @@
 	hidden in local directory listings.
 
 protocol.file.try_encoding_extensions [0|1] (default: 1)::
-	When set, if we can\'t open a file named \'filename', we'll try
+	When set, if we can\'t open a file named \'filename\', we\'ll try
 	to open \'filename\' with some encoding extension appended
 	(ie. \'filename.gz\'); it depends on the supported encodings.
 
@@ -1028,11 +1033,13 @@
 	If enabled, the capability to receive compressed content (gzip and/or
 	bzip2) is announced to the server, which usually sends the reply
 	compressed, thus saving some bandwidth at slight CPU expense.
-
-option. If (option. If that helps, there may be a bug in the decompression part)::
+	
+	If 'ELinks' displays a incomplete page or garbage, try disabling this
+	option. If that helps, there may be a bug in the decompression part
 	of 'ELinks'. Please report such bugs.
-
-has no (has no effect. To check the supported features, see Help -> About.)::
+	
+	If 'ELinks' has been compiled without compression support, this option
+	has no effect. To check the supported features, see Help -> About.
 
 protocol.http.trace [0|1] (default: 0)::
 	If active, all HTTP requests are sent with TRACE as their method
@@ -1073,7 +1080,7 @@
 
 protocol.nntp.header_entries <str> (default: "Subject,From,Date,Message-ID,Newsgroups")::
 	Comma separated list of which entries in the article header
-	to show. E.g. \'Subject\' and 'From'.
+	to show. E.g. \'Subject\' and \'From\'.
 	All header entries can be read in the header info dialog.
 
 protocol.rewrite::
@@ -1105,7 +1112,7 @@
 protocol.rewrite.default_template <str> (default: "")::
 	Default URI template used when the string entered in
 	the goto dialog does not appear to be a URI or a filename
-	(i.e. contains no \'.\', ':' or '/' characters), and does
+	(i.e. contains no \'.\', \':\' or \'/\' characters), and does
 	not match any defined prefixes. Set the value to "" to
 	disable use of the default template rewrite rule.
 	%c in the template means the current URL,
@@ -1123,7 +1130,7 @@
 	Enable smart prefixes - URI templates triggered by writing
 	given abbreviation to the Goto URL dialog followed by a list
 	of arguments from which the actual URI is composed - i.e.
-	\'gg:search keywords\' or 'gn search keywords for news'.
+	\'gg:search keywords\' or \'gn search keywords for news\'.
 
 protocol.user::
 	User protocols. Options in this tree specify external
@@ -1996,7 +2003,7 @@
 ui.sessions.homepage <str> (default: "")::
 	The URI to load either at startup time when no URI was given
 	on the command line or when requested by the goto-url-home action.
-	Set to "" if the environment variable WWW_'HOME' should be used
+	Set to "" if the environment variable 'WWW_HOME' should be used
 	as homepage URI instead.
 
 ui.sessions.keep_session_active [0|1] (default: 0)::
@@ -2006,6 +2013,8 @@
 	Automatically save a snapshot of all tabs periodically.
 	This will periodically bookmark the tabs of each terminal in a separate folder
 	for recovery after a crash.
+	
+	This feature requires bookmark support.
 
 ui.tabs::
 	Window tabs settings.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 188 bytes
Desc: not available
Url : http://linuxfromscratch.org/pipermail/elinks-dev/attachments/20080308/023d64a1/attachment.bin 

From fonseca at diku.dk  Sat Mar  8 06:12:08 2008
From: fonseca at diku.dk (Jonas Fonseca)
Date: Sat, 8 Mar 2008 14:12:08 +0100
Subject: [elinks-dev] doc/tools/help2doc rewrite in Perl
In-Reply-To: <87d4q6gkvo.fsf@Astalo.kon.iki.fi>
References: <87d4q6gkvo.fsf@Astalo.kon.iki.fi>
Message-ID: <20080308131208.GA2374@diku.dk>

Kalle Olavi Niemitalo <kon at iki.fi> wrote Sat, Mar 08, 2008:
> Here is a Perl version of doc/tools/help2doc.
> The shell version takes 1 min 33 s but this takes only 0.30 s.
> It generates an identical option-command.txt but fixes several bugs
> in option-config.txt, as you can see from the included diff.
> document.dump.separator is still not entirely right though.
> 
> OK to apply?  If not, please fix the shell version.

Nice! OK from here.

-- 
Jonas Fonseca

From kon at iki.fi  Sat Mar  8 08:28:10 2008
From: kon at iki.fi (Kalle Olavi Niemitalo)
Date: Sat, 08 Mar 2008 17:28:10 +0200
Subject: [elinks-dev] doc/tools/help2doc rewrite in Perl
In-Reply-To: <20080308131208.GA2374@diku.dk>
References: <87d4q6gkvo.fsf@Astalo.kon.iki.fi> <20080308131208.GA2374@diku.dk>
Message-ID: <87zlt9fd6d.fsf@Astalo.kon.iki.fi>

A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 188 bytes
Desc: not available
Url : http://linuxfromscratch.org/pipermail/elinks-dev/attachments/20080308/d60e59b8/attachment.bin 

From kon at iki.fi  Mon Mar 10 16:17:37 2008
From: kon at iki.fi (Kalle Olavi Niemitalo)
Date: Tue, 11 Mar 2008 00:17:37 +0200
Subject: [elinks-dev] new MIME handler assertion failure in 0.12.GIT
Message-ID: <87zlt65im6.fsf@Astalo.kon.iki.fi>

A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 188 bytes
Desc: not available
Url : http://linuxfromscratch.org/pipermail/elinks-dev/attachments/20080311/6128708a/attachment.bin 

From fonseca at diku.dk  Thu Mar 13 08:26:42 2008
From: fonseca at diku.dk (Jonas Fonseca)
Date: Thu, 13 Mar 2008 15:26:42 +0100
Subject: [elinks-dev] doc/tools/help2doc rewrite in Perl
In-Reply-To: <87zlt9fd6d.fsf@Astalo.kon.iki.fi>
References: <87d4q6gkvo.fsf@Astalo.kon.iki.fi> <20080308131208.GA2374@diku.dk>
	<87zlt9fd6d.fsf@Astalo.kon.iki.fi>
Message-ID: <20080313142642.GA18252@diku.dk>

Kalle Olavi Niemitalo <kon at iki.fi> wrote Sat, Mar 08, 2008:
> Jonas Fonseca <fonseca at diku.dk> writes:
> 
> > Kalle Olavi Niemitalo <kon at iki.fi> wrote Sat, Mar 08, 2008:
> >> OK to apply?  If not, please fix the shell version.
> >
> > Nice! OK from here.
> 
> There was still a bug in that one.  Apparently, because the
> option description is part of a list item, AsciiDoc wants its
> paragraphs to be separated with lines containing only "+".
> Also, if the second paragraph is indented like the first one,
> it will be indented deeper in the man page.  I fixed these in
> a new version, which I pushed to 0.12 and then merged to 0.13.
> It could be cherry-picked to 0.11 too but I'll let you decide
> whether to do that.

It looks good. For lists with items spanning mulitple paragrahps
there is a "list environment token":

--
 - First para.

Second para.
 - New item.
--

> AsciiDoc syntax seems full of traps for the unwary.
> It might be better to make help2doc generate DocBook,
> and then convert from that to HTML and man pages.
> An earlier version already did that though,
> so perhaps there was some reason to change it.

I have changed the ELinks documentation several times, most recently to
use AsciiDoc because I liked it and text files are easier. There are as
you mention many traps in the syntax of AsciiDoc. We could generate
"raw" DocBook and HTML and tell AsciiDoc to use that when compiling to
.xml and .html.

A different problem is the "syntax" of the option descriptions, which
are somewhat freeform when it comes to the int option "lists".

-- 
Jonas Fonseca

From kon at iki.fi  Sun Mar 23 12:45:28 2008
From: kon at iki.fi (Kalle Olavi Niemitalo)
Date: Sun, 23 Mar 2008 20:45:28 +0200
Subject: [elinks-dev] doc/tools/help2doc rewrite in Perl
In-Reply-To: <20080313142642.GA18252@diku.dk>
References: <87d4q6gkvo.fsf@Astalo.kon.iki.fi> <20080308131208.GA2374@diku.dk>
	<87zlt9fd6d.fsf@Astalo.kon.iki.fi> <20080313142642.GA18252@diku.dk>
Message-ID: <87prtl46uv.fsf@Astalo.kon.iki.fi>

A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 188 bytes
Desc: not available
Url : http://linuxfromscratch.org/pipermail/elinks-dev/attachments/20080323/e73a7caa/attachment.bin 

From kon at iki.fi  Mon Mar 24 09:41:35 2008
From: kon at iki.fi (Kalle Olavi Niemitalo)
Date: Mon, 24 Mar 2008 17:41:35 +0200
Subject: [elinks-dev] doc/tools/help2doc rewrite in Perl
In-Reply-To: <87prtl46uv.fsf@Astalo.kon.iki.fi>
References: <87d4q6gkvo.fsf@Astalo.kon.iki.fi> <20080308131208.GA2374@diku.dk>
	<87zlt9fd6d.fsf@Astalo.kon.iki.fi> <20080313142642.GA18252@diku.dk>
	<87prtl46uv.fsf@Astalo.kon.iki.fi>
Message-ID: <87wsns2kpc.fsf@Astalo.kon.iki.fi>

A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 188 bytes
Desc: not available
Url : http://linuxfromscratch.org/pipermail/elinks-dev/attachments/20080324/8c1929c5/attachment.bin