[prev in list] [next in list] [prev in thread] [next in thread] 

List:       gnuplot-info-beta
Subject:    RE: [Fwd: gnuplot doc2gih patch proposed]
From:       "Dick Crawford" <crawford () arete ! com>
Date:       2001-11-30 17:04:33
[Download RAW message or body]

On Friday, November 30, 2001 Hans-Bernhard Broeker wrote:

>On Fri, 30 Nov 2001, Guillaume Allègre wrote:
>
>> As I already told, I think there is a third alternative, which is
>> to use my patch only as a preprocessor, which would turn a meta-doc
>> file into traditionnal doc.
>
>That would not gain much. The .doc format of the file actually to be
>edited by developers would be the new one.  There's not much use storing
>the intermediated .doc file then, in this case.  So it's conceptually the
>same as integrating this filter as a subroutine linked to and called by
>the doc2*.c programs.
>
>> But the real question is : do you think it can help maintaining the doc
>> or it's useless ?
>
>It could certainly help. Correctly maintaining those '?' lines in
>gnuplot.doc has proven to be rather error-prone, as it is.  Any kind of
>simplification would help, I think. Actually, I think it would be best if
>the hierarchical structure could be automatically respected, i.e. if we
>have a node at level 3, with a "?foo bar baz" entry for it, then a level 4
>node attached to it and having a "?bang" line could get an automatically
>created "?foo bar baz bang" line added to it.  This would take care of the
>vast majority of current "?" lines in a single shot, I think.

As the guy who stuck most of the '?' lines into gnuplot.doc, I'll agree with
HBB that the current system is to some extent error-prone and inconsistent,
but I actually spent a lot of time trying to figure out a 'reasonable'
system.  Simple errors are my fault.  But many, if not indeed all, of the
inconsistencies stem from the fact that there are option names that appear
on several commands, so 'someone' has to decide which takes precedence.  For
example, "plot ... title" has its own entry, as does "set title".  "help
plot title" and "help set title" call up the appropriate texts; I decided
that "help title" would be a synonym for the "set" version.  Which would the
automated tool choose?  Would it be the same choice for all on-line formats?

We could design a system that recognizes multiple entries and queries the
user for more specific information:  "help title" might give the user a menu
like "Do you want help for 'set plot title', 'set title' or 'set key
title'?".  Having not thought this through, I don't know how difficult this
would be to implement.  If it were in place, though, we might well be able
to automate the whole thing.

Dick Crawford, aka crawford@arete.com


[[[[ unsubscribe from info-gnuplot-beta via majordomo@dartmouth.edu ]]]]

[prev in list] [next in list] [prev in thread] [next in thread]