Re: lynx-dev Re: what to do about html help files.

[Vlad Harchev]

On Fri, 28 May 1999, Henry Nelson wrote:

> > If the information is put into the HTML files, then remove it from the
> > lynx.cfg file.  However, frankly, I believe it belongs more in the
> > cfg file than html file.
> 
> Okay, I'm going to break my promise and speak up.  Leonid, I agree 100%
> with you that cattoc.html is a great innovation.  I think it holds a
> LOT of promise.  The only area where we disagree is _how_ it is done.
> 
> I think if you and Vlad would give it time to mature and evolve, there
> could be something quite useful created for Lynx users.  I sincerely
> hope you and Vlad will work on it so that Tom can slap it into the
> distribution at the very first round of the next develpment cycle
> without any reservations.
> 
> Toward this end, if I may:
> 1) You have not convinced me that body.html is necessary.  I could envision
> having one lynx.cfg (with a symbolic link to it from body.html -- maybe use
> a name like lynxcfg.html, though) that contains "html" in it.  To use my
> example of the other day:
> 
> ##</pre><h2><a name="HISTORICAL_COMMENTS">HISTORICAL_COMMENTS</a><!--
> ##-->&nbsp; - <a href="cattoc.html#HTML">HTML parsing</a><!--
> ##-->&nbsp; ][ <a href="LYNXSETTINGSTATUS://HISTORICAL_COMMENTS">Status of 
> this setting</a></h2><p><pre>
> # If HISTORICAL_COMMENTS is TRUE, Lynx will revert to the "Historical"
> # behavior of treating any '&gt;' as a terminator for comments, instead of
> # seeking a valid '--&gt;' terminator (note that white space can be present
> # between the '--' and '&gt;' in valid terminators).  The compilation default
> # is FALSE.
> #
> # The compilation default, or default defined here, can be toggled via a
> # "-historical" command line switch, and via the LYK_HISTORICAL command key.
> #
> #HISTORICAL_COMMENTS:FALSE
> 
> The illegal entities are a bit ugly to handle.  I would do it with a simple
> explanation; others might prefer a sed one-liner to convert at installation.
> A short gawk script could do most of the work; even hand editing would only
> take an afternoon or so.

 I don't like the idea of combining body.html and lynx.cfg. Or lynx will be a
software package that doesn't have separate documentaion on its configuration
settings since all docs will be placed inside lynx.cfg.
 And users are free do delete comments from lynx.cfg, so we shouldn't expect
that the comments we emit to lynx.cfg will be there.

>[...]

> 3) No matter which route you go, it is totally unreasonable to have two
> complete mechanisms for reviewing the active lynx.cfg file and the default
> lynx.cfg.  The one that is already in there off of the = page isn't even
> being used as is.  You talk about some 40KB compressed file, but in fact
> you are asking (forcing, for the first two) people to install *3* lynx.cfg
> files: their own, the 90+KB distribution lynx.cfg (needed for the
> "Please read the distribution [1]lynx.cfg for more comments." link, and
> now a 180+KB markup of the lynx.cfg under the help subdirectory.

 As for number of files:
 The user's own file can be of any size.
 Users don't have to preserve distribution's lynx.cfg. LYNXCFG:// page says
the following:

This is read from your lynx.cfg file,
please "read" distribution's lynx.cfg for more comments.

 This means that distribution's lynx.cfg is treated as documentation for all
settings. If we'll intergrate body.in, then (IMO) this sentence will be
changed something like this:

This is read from your lynx.cfg file,
see documentation on the settings in lynx.cfg _here_. 

 or something like that referencing body.html or cattoc.html.

 Moreover, my patch makes every setting name on LYNXCFG:// page to be the
link to the documentation on this option.
 
 As for useless of LYNXCFG:// page:
 IMO it's very useful, since there are a lot of tasks that you can't perform
using only LYNXSETTINGSTATUS:// url:
1) What files are read (remember INCLUDE command)
2) What settings are allowed in which file (remember extended syntax of
INCLUDE command that allows included file to accept only subset of lynx
settings)
3) What settings were initalized in a whole (ie what settings don't take
default value)
4) Not yet fully implemented: reload the configuration files

 To perform these tasks, you'll have to check LYNXSETTINGSTATUS:// pages for
all 151 settings, and mentally make a set union of gathered information. At
least it'll take some time :)

> If you chose to go Vlad's route, then completely backout all of the
> lynx.cfg help that's in the code now: all those links to files, all those
> gettext() messages and code generated html pages, LYNXCFG://reload/, etc.,
> etc.  I think Vlad's way is much better, but it is a BIG undertaking to get
> rid of the trappings that are going to be made obsolete.  It is not Tom's
> responsibility to clean up after other people's mess.  I will continue to
> lift the wool people are trying to pull over the eyes of lynx-devers.

 So, IMO, LYNXCFG:// and LYNXSETTINGSTATUS:// complement each other, rather
then interfere.

> __Henry
> 

 Best regards,
  -Vlad