Mailing List Archive

> > Who is currently working on the manual for gpg? It is mentioned on the
> > web page as not yet being done.
>
> AFAIK nobody. Somebody (Michael Deindl) has started a manual a few month
> ago but is not reachable anymore nor is the manual useable (only a few
> headings; nothing more).
>
I would be interested on working on such a document, and while the
US government would throw a fit if I were working on the code, I don't
think their is a problem with me writing documentation. The biggest
disadvantage is that I am new to using gpg, but I suppose that using it
will fix that. :)

From,
Matthew M. Copeland

I suggest a PDF formatted manual since you can do:
- Nice Illustration / WYSYWIG format
- Hyperlinks
- Platform Independent
- Build forms processing into the PDF file
- Free reader on every platform, including Linux!

I can help out with this too. I have Acrobat 3.0.1/Exchange that can create,
and modify PDF files.

Jeffrey Thompson

At 06:40 AM 1/27/99 -0600, you wrote:
>
>Who is currently working on the manual for gpg? It is mentioned on the
>web page as not yet being done.
>
>From,
>Matthew M. Copeland
>
>

On Thu, Jan 28, 1999 at 10:58:17AM -0500, Jeffrey Thompson wrote:
>I suggest a PDF formatted manual since you can do:
>- Nice Illustration / WYSYWIG format
>- Hyperlinks
>- Platform Independent
>- Build forms processing into the PDF file
>- Free reader on every platform, including Linux!

No deliberate offence to Jeffrey, but:

No good if you don't want a non-open-source, heavyweight application
clogging up your system. Or you have a telnet-only connection. Or you
care about the file size.

Plain text is WYSIWYG by definition, a whole lot more platform-
independent and free-readerish. If we really need pretty pictures we
can always have a PDF version as well.

I might as well take this opportunity to volunteer to help with /
do large parts of the docs.

Cheers,

Roger

On Thu, Jan 28, 1999 at 10:58:17AM -0500, Jeffrey Thompson wrote:
> I suggest a PDF formatted manual since you can do:
> - Nice Illustration / WYSYWIG format
> - Hyperlinks
> - Platform Independent
> - Build forms processing into the PDF file
> - Free reader on every platform, including Linux!
>
> I can help out with this too. I have Acrobat 3.0.1/Exchange that can create,
> and modify PDF files.

Oh please no. Perhaps as one of the formats available, but certainly
not the only format. Many of us hate it because the acrobat reader
is really clumsy and horribly implemented. Lets start out with text
documentation and then do HTML. It's much more portable!

** Martin

>>>>> "Jeffrey" == Jeffrey Thompson
>>>>> "Re: Manual Contact"
>>>>> Thu, 28 Jan 1999 10:58:17 -0500


Jeffrey> I suggest a PDF formatted manual since you can do:
Jeffrey> - Nice Illustration / WYSYWIG format
Jeffrey> - Hyperlinks
Jeffrey> - Platform Independent
Jeffrey> - Build forms processing into the PDF file
Jeffrey> - Free reader on every platform, including Linux!

Jeffrey> I can help out with this too. I have Acrobat
Jeffrey> 3.0.1/Exchange that can create, and modify PDF files.

AFIK pdf prints nicely but is very unattractive if not unusable for
reading "on-line". Nothing beats GNU info IMHO. The linux
documentation project has a sgmltools package that works on several
platforms and produces LaTeX, HTML, GNU info, LyX, RTF, plain ASCII
(via groff), and more from a single source. See
<http://www.sgmltools.org/>.

jam

On Thu, Jan 28, 1999 at 07:46:28PM -0700, Michael Roth wrote:
> I suggest using a XML based system. For example the widly known `docbook'.
> You can process XML documents to generate all sort of documents, even PDF
> should be possible.

I am not that sure that "widely know `docbook'" is XML based. It is SGML
based. XML-based docbook is in beta stage or something like that.

--
Mike

I think that I like this last option best. The ability to distribute a
file in mutliple formats that are easily readable is probably the best
idea. One problem with PDF files is that they have a tendency to grow
rather large quickly in comparison to other file formats, thus it will
take a while to download compared to say a text version, or an HTML
version. I am looking at the sgmltools web site now.

From,
Matthew M. Copeland



On Thu, 28 Jan 1999, John A. Martin wrote:

> >>>>> "Jeffrey" == Jeffrey Thompson
> >>>>> "Re: Manual Contact"
> >>>>> Thu, 28 Jan 1999 10:58:17 -0500
>
>
> Jeffrey> I suggest a PDF formatted manual since you can do:
> Jeffrey> - Nice Illustration / WYSYWIG format
> Jeffrey> - Hyperlinks
> Jeffrey> - Platform Independent
> Jeffrey> - Build forms processing into the PDF file
> Jeffrey> - Free reader on every platform, including Linux!
>
> Jeffrey> I can help out with this too. I have Acrobat
> Jeffrey> 3.0.1/Exchange that can create, and modify PDF files.
>
> AFIK pdf prints nicely but is very unattractive if not unusable for
> reading "on-line". Nothing beats GNU info IMHO. The linux
> documentation project has a sgmltools package that works on several
> platforms and produces LaTeX, HTML, GNU info, LyX, RTF, plain ASCII
> (via groff), and more from a single source. See
> <http://www.sgmltools.org/>.
>
> jam
>

Can you give me a reference for docbook? I haven't heard of it.

On Thu, 28 Jan 1999, Michael Roth wrote:

> On Thu, 28 Jan 1999, Jeffrey Thompson wrote:
>
> > I suggest a PDF formatted manual since you can do:
>
> I suggest using a XML based system. For example the widly known `docbook'.
> You can process XML documents to generate all sort of documents, even PDF
> should be possible.
>
> Further more, XML is an open and public specification.
>
>
> cu
> Michael
>
>
>
>

I'm a pretty good idiot user... :-)

Sign me up for "review manual and ask stupid questions that lead to more
complete explanations".

I don't really care which format, but it might make sense to have several
formats derived from a common source, with somebody to volunteer for each
format to "clean up" after each re-publication. I don't even know what
that GNU thing is, by the way... but suspect it wouldn't be too useful to
your average Windows or Mac user who wants to use gpg with their e-mail
client...

Make the docs open-source as well, with CVS. Even better, for non-hackers
who can't figure out CSV, perhaps a feature like ca.php.net "Add Note".
Any web surfer can add a note to ask about a piece of the docs they don't
understand, and more knowledgable surfers add notes explaining in more
detail, or examples, or point out weird cases that need to be documented.
The PHP documentation team regularly goes through and incorporates,
discards, reworks, etc the manual based on the online notes. The good
thing is, the notes are visible in the meantime, and they are generally
placed by users in the appropriate section of the manual, so the editing
nightmare of keeping suggestions organized is much easier.

-- "TANSTAAFL" Rich lynch@cognitivearts.com webmaster@ and www. all of:
R&B/jazz/blues/rock - jademaze.com music industry org - chatmusic.com
acoustic/funk/world-beat - astrakelly.com sculptures - olivierledoux.com
my own nascent company - l-i-e.com cool coffeehouse - uncommonground.com

>>>>> "Matthew" == Matthew M Copeland
>>>>> "Re: Manual Contact"
>>>>> Thu, 28 Jan 1999 13:47:17 -0600 (EST)


Matthew> Can you give me a reference for docbook? I haven't heard
Matthew> of it.

Check <http://www.sgmltools.org/>. sgmltools uses docbook.

jam

>>>>> Matthew M Copeland <dyelar@rdl.ml.org> writes:

> One problem with PDF files is that they have a tendency to grow
> rather large quickly in comparison to other file formats...

I think that this is only true if you assume that PDF == Windows. If
you instead start with good Postscript code, you'll end up with a good
PDF. PDF's flate compression will normally result in PDFs that are
*smaller* than the text original.

For example, we write our technical documents in LaTeX (with LyX), but
usually have to convert them to PDF for distribution to our customers.
A typical 100-page specification might be a 400K TeX file, which
results in a 550K PS file, which gets converted (by pstill or ps2pdf)
to a 155K PDF (compared to 95K for the gzipped TeX file).

The only standard doc format smaller than this would be a gzipped info
file or man pages, and these don't support images. The HTML
equivalent
would be much larger.

I think that the ability to distribute files in multiple formats is a
*good* thing -- and smgltools is a good way to do this -- but don't
knock PDFs on the basis of size or the need for Windoze or Adobe
Distiller, as neither of these assumptions is accurate.

(BTW, I usually use gv instead of acroread to read PDFs.)

--
Roger Williams finger me for my PGP public key
Coelacanth Engineering Inc consulting & turnkey product development
Middleborough, Massachusetts wireless * datacomm * DSP * ATE
tel +1 508 947-5585 * fax +1 508 861-0278 * http://www.coelacanth.com/

>>>>> "Roger" == Roger Williams
>>>>> "Re: Manual Contact"
>>>>> Thu, 28 Jan 1999 23:09:25 +0000

>>>>> Matthew M Copeland <dyelar@rdl.ml.org> writes:
Roger> I think that the ability to distribute files in multiple
Roger> formats is a *good* thing -- and smgltools is a good way to
Roger> do this -- but don't knock PDFs on the basis of size or the
Roger> need for Windoze or Adobe Distiller, as neither of these
Roger> assumptions is accurate.

Right.

Roger> (BTW, I usually use gv instead of acroread to read PDFs.)

How do you do it on a character terminal?

Don't forget that among the potential users of gpg are folks operating
under various disadvantages. IMHO all pgp documentation should be
accessible with the very minimum facilities.

The documentation for pgp has always been usable with the simplest
equipment. Changing that would not be an improvement.

jam

> I'm a pretty good idiot user... :-)
>
> Sign me up for "review manual and ask stupid questions that lead to more
> complete explanations".

That sounds great.

>
> I don't really care which format, but it might make sense to have several
> formats derived from a common source, with somebody to volunteer for each
> format to "clean up" after each re-publication. I don't even know what
> that GNU thing is, by the way... but suspect it wouldn't be too useful to
> your average Windows or Mac user who wants to use gpg with their e-mail
> client...
>
> Make the docs open-source as well, with CVS. Even better, for non-hackers
> who can't figure out CSV, perhaps a feature like ca.php.net "Add Note".
> Any web surfer can add a note to ask about a piece of the docs they don't
> understand, and more knowledgable surfers add notes explaining in more
> detail, or examples, or point out weird cases that need to be documented.
> The PHP documentation team regularly goes through and incorporates,
> discards, reworks, etc the manual based on the online notes. The good
> thing is, the notes are visible in the meantime, and they are generally
> placed by users in the appropriate section of the manual, so the editing
> nightmare of keeping suggestions organized is much easier.
>
Okay, I can understand using CVS. That is kind of a must. Open
Source is the only way it would go out also. As for having a web-enabled
comment system might be interesting, do you have code for this? It won't
be applicable really until we get a basic document together, but at some
point later it will be. (Say around the time when we start asking people
outside the group for comments.)


> -- "TANSTAAFL" Rich lynch@cognitivearts.com webmaster@ and www. all of:
> R&B/jazz/blues/rock - jademaze.com music industry org - chatmusic.com
> acoustic/funk/world-beat - astrakelly.com sculptures - olivierledoux.com
> my own nascent company - l-i-e.com cool coffeehouse - uncommonground.com
>
>
>

>>>>> John A Martin <jam@jamux.com> writes:

> IMHO all pgp documentation should be accessible with the very
> minimum facilities.

I agree. For me, that means Emacs info, but I suppose that *could* be
considered optional... ;-)

Despite my defence of PDF, I usually find HTML to be the most
convenient format for browsing hyperlinked *text* documentation, for
which I use Lynx, Netscrape, or W3, depending on bandwidth. It's
certainly a widely-supported, platform-independent format.

OTOH, HTML is a pain to distribute (gzipped tar file), and takes a lot
of space after it's installed. (And for our own technical docs, we
need something that can display vector drawings, like PS or PDF.)

I suspect that 'very minimum' means man pages for *nix, text files
(no screen codes) for any other OS.

--
Roger Williams finger me for my PGP public key
Coelacanth Engineering Inc consulting & turnkey product development
Middleborough, Massachusetts wireless * datacomm * DSP * ATE
tel +1 508 947-5585 * fax +1 508 861-0278 * http://www.coelacanth.com/

> I think that this is only true if you assume that PDF == Windows. If
> you instead start with good Postscript code, you'll end up with a good
> PDF. PDF's flate compression will normally result in PDFs that are
> *smaller* than the text original.
>
> For example, we write our technical documents in LaTeX (with LyX), but
> usually have to convert them to PDF for distribution to our customers.
> A typical 100-page specification might be a 400K TeX file, which
> results in a 550K PS file, which gets converted (by pstill or ps2pdf)
> to a 155K PDF (compared to 95K for the gzipped TeX file).

> I think that the ability to distribute files in multiple formats is a
> *good* thing -- and smgltools is a good way to do this -- but don't
> knock PDFs on the basis of size or the need for Windoze or Adobe
> Distiller, as neither of these assumptions is accurate.

I stand corrected. :) I think that if we can produce an sgml version and
then a postscript version that we can then pop out a pdf version.
Everyone is then happy.

From,
Matthew M. Copeland

> How do you do it on a character terminal?
>
> Don't forget that among the potential users of gpg are folks operating
> under various disadvantages. IMHO all pgp documentation should be
> accessible with the very minimum facilities.
>
> The documentation for pgp has always been usable with the simplest
> equipment. Changing that would not be an improvement.
>
> jam

This shouldn't be to much of a problem since sgmltools will output in a
GNU info file, or plain ASCII if needed.

sgmltools outputs the following formats LaTex, HTML, GNU Info, RTF, and
plain ASCII (via groff) according www.sgmltools.org.

At 6:21 PM 1/28/99, Matthew M. Copeland wrote:
>> Even better, for non-hackers
>> who can't figure out CSV, perhaps a feature like ca.php.net "Add Note".
>> Any web surfer can add a note to ask about a piece of the docs they don't
>> understand, and more knowledgable surfers add notes explaining in more
>> detail, or examples, or point out weird cases that need to be documented.
>> The PHP documentation team regularly goes through and incorporates,
>> discards, reworks, etc the manual based on the online notes. The good
>> thing is, the notes are visible in the meantime, and they are generally
>> placed by users in the appropriate section of the manual, so the editing
>> nightmare of keeping suggestions organized is much easier.

>As for having a web-enabled
>comment system might be interesting, do you have code for this? It won't
>be applicable really until we get a basic document together, but at some
>point later it will be. (Say around the time when we start asking people
>outside the group for comments.)

Source code in PHP is available at ca.php.net

-- "TANSTAAFL" Rich lynch@cognitivearts.com webmaster@ and www. all of:
R&B/jazz/blues/rock - jademaze.com music industry org - chatmusic.com
acoustic/funk/world-beat - astrakelly.com sculptures - olivierledoux.com
my own nascent company - l-i-e.com cool coffeehouse - uncommonground.com

On Thu, 28 Jan 1999, Jeffrey Thompson wrote:

> I suggest a PDF formatted manual since you can do:

I suggest using a XML based system. For example the widly known `docbook'.
You can process XML documents to generate all sort of documents, even PDF
should be possible.

Further more, XML is an open and public specification.


cu
Michael

On Thu, 28 Jan 1999, Matthew M. Copeland wrote:

> Can you give me a reference for docbook? I haven't heard of it.

Oh sorry, here the links... ;-)


DocBook
-------
[1] http://www.oasis-open.org/docbook/
[2] http://www.gr.opengroup.org/adl/papers/sgml_setup.html
[3] http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html

XML
---
[1] http://www.w3.org/XML/
[2] http://www.ntlug.org/~kclark/roadmap/


cu
Michael

On Thu, 28 Jan 1999, Michael Sobolev wrote:

> I am not that sure that "widely know `docbook'" is XML based. It is SGML
> based. XML-based docbook is in beta stage or something like that.

Yes you are right. I was wrong. ;-)


cu
Michael

Matthew M. Copeland :
------------------------------------------------------------

> I stand corrected. :) I think that if we can produce an sgml version and
> then a postscript version that we can then pop out a pdf version.
> Everyone is then happy.

this is why I started with sgml for the manual ;-)

regards
Stefan

--
Sie haben den Mauszeiger bewegt. Starten Sie das System neu,
um die Änderung wirksam werden zu lassen...