trn

In <200006021857.OAA07961@...>,
Charles Seeger <seeger@...> wrote:
>+------ Colin Watson wrote (Fri,  2-Jun-00, 19:28 +0100):
>| What's the current status of trn(1) (i.e. is anyone working on it or
>| does anyone have any ideas about what should be done to it before 4.0)?
>| 
>| The main problem I see is that it's too long; over 30 pages when
>| rendered into PostScript. Much of this information is duplicated
>| elsewhere. For instance, the new HelpFiles/config/environment contains a
>| more up-to-date version of nine of these pages, ...
>| 
>| In the interests of avoiding having to keep two copies of the same
>| document in sync, would there be significant opposition to replacing
>| almost half of the man page with references to the online documentation?

Re duplication of content, IMHO, "less is more" - if the verbose
interactive h/?/H output of trn is informative, then there's no point in
trying to keep 2 copies in sync in the code source & documents.  

The CLI options need to be in an external document, and this would be a
good opportunity to merge content from other trn documents (intro, FAQ)
back into the distribution documents, but I would suggest trying to keep
the 'man page' proliferation down to perhaps 4 or 5 major chunks so that
new-ish users don't have to explore 10-12 docs in search of one or two
answers - killfiles and scoring seem to break out easily, and perhaps
macros and access files - but I would stop there.

Re format choices, any source & auto-generated target formats beyond a
man page are fine with me, but if a setup requires sync'ing multiple
sources, or targets require hand-editing to be usable then we're right
back into the "help wanted with doc updates" swamp - and who needs that?
 
>       trn-intro(1): see Jon Bell's <jtbell@...> intro...
>                       ftp://cs1.presby.edu/pub/trn-intro/
 
Jon is travelling a lot this month, so don't take silence from him as a
definitive response one way or the other.  I'm not volunteering him,
just pointing out that his net access is limited during June.


-- 
Denis McKeon

On Fri, 02 Jun 2000 at 14:57:00 -0400, Charles Seeger wrote:
> +------ Colin Watson wrote (Fri,  2-Jun-00, 19:28 +0100):
> | In the interests of avoiding having to keep two copies of the same
> | document in sync, would there be significant opposition to replacing
> | almost half of the man page with references to the online documentation?
> 
> Personally, I think that the trn(1) man page should be broken into
> a few separate parts, e.g. trn-killfile, trn-scoring, etc.  Ideally
> these man pages and the online help would be generated from a common
> source of some kind.

I agree, here, in line with the comment that online help files aren't
easily printable (at least not nicely). SGML source seems to be the
current standard for this kind of thing, distributed pre-built and with
a convenient Makefile so that other people can update the documentation.

>   http://www.wired.ml.org/trn-workers/1998/msg00458.html

Wish I'd known about this when it was still available ... is there a
similar archive available anywhere now?

> 	trn-intro(1): see Jon Bell's <jtbell@...> intro...
> 			ftp://cs1.presby.edu/pub/trn-intro/

The licence on this specifies non-commercial use only - how will this
sit with moving to a BSD-style licence?

[snip list]

Some work lies ahead, then. :)

-- 
Colin Watson                                     [cjw44@...]

Re: format

Unfortunately there is no text format which covers all these criteria:

a. people know
b. easy to edit
c. converts into other formats easily

Currently, man pages are the best for the trn distribution because that's
a format users are used to installing and using via the man command.

PDF is really bad for people using text - one of the primary reasons I know
I use trn today.

HTML is really bad to get right and is tough to convert in the various other
formats that people want.

POD is close to perfect; easy for people to learn, relatively easy to edit,
and easy to convert.  However, as was mentioned, it wouldn't be very useful
to be the main distribution format as it would require users to install perl.

Perhaps this could be done - documentors could use POD to write the doc.
Then, when preparing the doc for distribution, they could generate man
pages the pod.  There could even be different install actions for people who
want the doc in other formats - just document that they need to install
perl to get the converters into the other formats.  
-- 
Larry W. Virden <mailto:lvirden@...>
<URL: http://www.purl.org/NET/lvirden/>
Unless explicitly stated to the contrary, nothing in this posting should 
be construed as representing my employer's opinions.
-><-

In article <0006031623.AA29622@...>,
    "Larry W. Virden" <lvirden@...>  writes:

> HTML is really bad to get right and is tough to convert in the various other
> formats that people want.

HTML should only be considered as a derivative of whatever source
format is used for the documentation.  There are good converters to
HTML from info and from man page formats.  There is also the
possibility of doing a small 'home brew' format that takes a single
document with simple instructions and uses sed/awk/etc. to process it
into the segmented online help files and the man page.

This is essentially what POD does in the way it processes the
documentation.  Fractint has something similar for its extensive
online help -- it can generate a big document from the online help
resources.  I think having one source for the docs is important, just
that the man page not be left out in the cold in favor of *only*
online help.  Especially when it shouldn't be hard to generate one
from the other.
--
<http://www.xmission.com/~legalize/>	Legalize Adulthood!
    ``Ain't it funny that they all fire the pistol,     
      at the wrong end of the race?''--PDBT     
legalize@...	<http://www.xmission.com/~legalize/who/>

I vote for pod.

Is about as simple as you can get!

(whereas html, troff, etc ... are definitely NOT)

David

The info browser I like best is tkman - it can read both man pages AND
info files.
-- 
Larry W. Virden <mailto:lvirden@...>
<URL: http://www.purl.org/NET/lvirden/>
Unless explicitly stated to the contrary, nothing in this posting should 
be construed as representing my employer's opinions.
-><-

On Sun, Jun 04, 2000 at 02:30:07PM -0700, Steve Schlaifer wrote:
> Can you send me a URL for where to find pod?  I'm interested for other
> applications but a brief attempt at using a search engine hit lots of
> games but nothing about documentation.  Thanks for the help.
> 

To WRITE pod takes merely an editor.

But to CONVERT it to anything requires the perl programs
that do that -- which in turn requires having an entire
perl distribution downloaded and running.

(Because perl is an "interpreter" -- perl programs are
useless without a perl running on your system.)


>From my bookmarks file:

http://www.perl.com/perl/info/software.html

is the place from which to download perl sources.

IF you are using a PC with windows, I believe you
have to search for a place called "activestate",
which provides free downloads of perl-binaries -- no
compiling or gcc needed.

And I believe that is the ONLY decent way to get a
perl running on a M$ system.

Perhaps there is a link TO activestate ON that
site I listed above.

Hope this helps.

David

In article <20000605164436.D28585@...>,
    David Combs <dkcombs@...>  writes:

> To WRITE pod takes merely an editor.
> 
> But to CONVERT it to anything requires the perl programs
> that do that -- which in turn requires having an entire
> perl distribution downloaded and running.

True, but you only need do the conversion once when incorporating
documentation into the distribution.
--
<http://www.xmission.com/~legalize/>	Legalize Adulthood!
    ``Ain't it funny that they all fire the pistol,     
      at the wrong end of the race?''--PDBT     
legalize@...	<http://www.xmission.com/~legalize/who/>

Phil McRevis wrote:
> David Combs writes:
>>
>> To WRITE pod takes merely an editor.
>>
>> But to CONVERT it to anything requires the perl programs that do
>> that -- which in turn requires having an entire perl distribution
>> downloaded and running.
> 
> True, but you only need do the conversion once when incorporating
> documentation into the distribution.

How so?  We're talking source distributions, not binary.  I would expect
the original documentation sources to be included with the source
distribution, and have the makefile generate any other formats.

If the post-compiled documentation is included in the distribution,
people who want to make changes will have to hunt down the originals
before they can do so.

If both the originals and the post-compiled docs are included, then we
have the problem of keeping them synchronized with each other.

If there was a binary distribution of trn, I'd feel otherwise.  It would
be reasonable to expect people compiling the code to have all the tools
necessary if these people were a small group of trn developers.  But
when every person using the program must compile his own copy, issues
like these become significant.

Then again, it may be enough to just tell everyone that they need perl
in order to compile the documentation.  I think Cygnus has a free
distribution that Windows users can download.  I know that nearly all
UNIX distributions include it these days.

-- David

On Tue, 06 Jun 2000 at 12:03:21 -0400, David Charlap wrote:
> Phil McRevis wrote:
> > True, but you only need do the conversion once when incorporating
> > documentation into the distribution.
> 
> How so?  We're talking source distributions, not binary.  I would expect
> the original documentation sources to be included with the source
> distribution, and have the makefile generate any other formats.
> 
> If the post-compiled documentation is included in the distribution,
> people who want to make changes will have to hunt down the originals
> before they can do so.
> 
> If both the originals and the post-compiled docs are included, then we
> have the problem of keeping them synchronized with each other.

I don't think that would be a problem. A 'make dist' or whatever before
releasing would clean that up. Consider the situation of configure
scripts; they're built from source, but distributed pre-built, and this
isn't regarded as a problem.

I would expect the documentation sources to be included *as well as* the
built versions, with a README file saying which is which; would that
really be so confusing? I think it's quite common to distribute SGML
sources for documentation pre-built into HTML, text, and so on.

-- 
Colin Watson                                     [cjw44@...]

On Tue, 6 Jun 2000, David Charlap wrote:
> If both the originals and the post-compiled docs are included, then
> we have the problem of keeping them synchronized with each other.

This isn't a problem if you put the rules for building the docs into
the Makefile.  Then, if you distribute certain files pre-built (e.g.
the nroff man pages), normal folks won't trigger those build rules.
As for alternate doc formats (such as HTML), I assume we'd have extra
Makefile targets to build them (requiring the presence of perl), but
we could also make a separate doc tar file available (if we want) that
would include all the possible output formats pre-built (for those
without perl).

Consider the "zsh" distribution.  They use yodl files for all their
documentation (yodl is quite a bit more complex than pod, and I'm not
really all that familiar with it).  Though you need yodl in order to
build the man pages from a cvs checkout, their tar-file distributions
contain both the yodl source files and the man pages, so normal people
don't need yodl.

..wayne..

Re: distributing multiple formats

One thing that can be done to help keep things 'in sync' is to make
certain to name directories, etc. in such a way that people realize what
things are 'patchable' and what things are generated and thus should not
be patched.
-- 
Larry W. Virden <mailto:lvirden@...>
<URL: http://www.purl.org/NET/lvirden/>
Unless explicitly stated to the contrary, nothing in this posting should 
be construed as representing my employer's opinions.
-><-