LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity

Updates from the ldp-submit list.

This commit is contained in:
gleblanc 2000-05-09 16:22:20 +00:00
parent a55cb26861
commit b5284661c6
2 changed files with 328 additions and 210 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

227
LDP/howto/docbook/HOWTO-HOWTO.sgml
View File

@ -9,9 +9,9 @@
<title>
HOWTO-HOWTO
</title>
<pubdate>
2000/04/17
</pubdate>
<date>
v1.6 3 May, 2000
</date>
<author>
<firstname>Mark</firstname><surname>Komarinski</surname>
</author>
@ -46,7 +46,7 @@
Comments
</title>
<para>
Comments on this HOWTO may be directed to the author (markk@cgipc.com).
Comments on this HOWTO may be directed to the author (<ulink url="mailto:markk@linuxdoc.org">markk@linuxdoc.org</ulink>).
</para>
</sect2>
<sect2>
@ -54,22 +54,22 @@
Version History
</title>
<para>
v1.3 (March 3, 2000)
v1.6 (May 3, 2000)
</para>
<itemizedlist>
<listitem>
<para>
Comments from Gregory Leblanc on LDP submissions.
Updated tools section thanks to Greg Ferguson
</para>
</listitem>
<listitem>
<para>
Comments from other readers. Thank you all!
No more updates on LinuxDoc documentation. Sorry.
</para>
</listitem>
<listitem>
<para>
Frist distributed version in DocBook using Lyx and DB 3.1.
More LyX documentation
</para>
</listitem>
</itemizedlist>
@ -125,7 +125,7 @@
The LDP
</title>
<para>
The Linux Documentation Project (LDP) was started to provide new users a way of getting information quickly about a particular subject. It not only contains a series of books on administration, networking, and programming, but has a large number of smaller works on individual subjects, written by those who have used it. If you want to find out about printing, you get the Printing HOWTO. If you want to do some networking, grab the Ethernet HOWTO, and so on. At first, many of these works were in text or HTML. As time went on, there had to be a better way of managing these documents. One that would let you read it from a web page, a text file on a CD-ROM, or even your hand-held PDA. The answer, as it turns out, is SGML.
The Linux Documentation Project (LDP) was started to provide new users a way of getting information quickly about a particular subject. It not only contains a series of books on administration, networking, and programming, but has a large number of smaller works on individual subjects, written by those who have used it. If you want to find out about printing, you get the Printing HOWTO. If you want to do find out if your Ethernet card works with Linux, grab the Ethernet HOWTO, and so on. At first, many of these works were in text or HTML. As time went on, there had to be a better way of managing these documents. One that would let you read it from a web page, a text file on a CD-ROM, or even your hand-held PDA. The answer, as it turns out, is SGML.
</para>
</sect2>
<sect2>
@ -133,7 +133,7 @@
SGML
</title>
<para>
The Standard Generalized Markup Language (SGML) is a language that is based on embedding codes within a document. In this way, its similar to HTML, but there is where any similarities end. The power of SGML is that unlike WYSIWYG (What You See Is What You Get), you don't define things like colors, or font sizes, or even some kinds of formatting. Instead, you define elements (paragraph, section, numbered list) and let the SGML processor and the end program worry about placement, colors, fonts, and so on. HTML does the same thing, and is actually a subset of SGML. SGML has really two parts that make it up. First is the Structure, which is what is commonly called the DTD, or Document Type Definition. The DTD defines the relationship between each of the elements. The LinuxDoc DTD, used to create this document, is an example of this. The DTD gives a common look and feel to each document that's created using the DTD. Second is the Content, which is what gets rendered by the SGML processor and is eventually seen by the user. This paragraph is content, but so would a graphic image, table, numbered list, and so on. Content is surrounded by tags to separate out each different element. Over time, the LinuxDoc DTD is going to change over to the DocBook DTD, used by others and giving the LDP a consistent look and feel to other SGML documentation. As this happens, we'll keep you updated via this HOWTO or on the mailing lists. The biggest difference between LinuxDoc and DocBook is that DocBook assigns tags to different types of content (such as commands, file names, directories, and so on) while LinuxDoc assigns tags based on the way the text should look (you can assign emphasized or typewriter for example)
The Standard Generalized Markup Language (SGML) is a language that is based on embedding codes within a document. In this way, its similar to HTML, but there is where any similarities end. The power of SGML is that unlike WYSIWYG (What You See Is What You Get), you don't define things like colors, or font sizes, or even some kinds of formatting. Instead, you define elements (paragraph, section, numbered list) and let the SGML processor and the end program worry about placement, colors, fonts, and so on. HTML does the same thing, and is actually a subset of SGML. SGML has really two parts that make it up. First is the Structure, which is what is commonly called the DTD, or Document Type Definition. The DTD defines the relationship between each of the elements. The DocBook DTD, used to create this document, is an example of this. The DTD gives a common look and feel to each document that's created using the DTD. Second is the Content, which is what gets rendered by the SGML processor and is eventually seen by the user. This paragraph is content, but so would a graphic image, table, numbered list, and so on. Content is surrounded by tags to separate out each element.
</para>
</sect2>
<sect2>
@ -141,7 +141,7 @@
Why SGML instead of HTML or other formats?
</title>
<para>
SGML provides for more than just formatting. You can automatically build indexes, table of contents, and links within the document or to outside. The sgmltools package also lets you export (I'll call it render from here on) SGML to LaTeX, info, text, HTML, and RTF. From these basic formats, you can then create other formats (DOC, PostScript, and so on). Programs like LyX (right now my LinuxDoc editor of choice) allow you to write in TeX format, then export it as SGML and render from SGML to whatever you chose. In the end, SGML is more concerned about the way elements work instead of the way they look. A big distinction, and one that will let you write faster, since you don't have to worry about placement of paragraphs, font sizes, font types, and so on.
SGML provides for more than just formatting. You can automatically build indexes, table of contents, and links within the document or to outside. The sgmltools package also lets you export (I'll call it render from here on) SGML to LaTeX, info, text, HTML, and RTF. From these basic formats, you can then create other formats such as MS Word, PostScript, PDF and so on. Programs like LyX allow you to write in TeX format, then export it as SGML and render from SGML to whatever you chose. In the end, SGML is more concerned about the way elements work instead of the way they look. A big distinction, and one that will let you write faster, since you don't have to worry about placement of paragraphs, font sizes, font types, and so on.
</para>
</sect2>
<sect2>
@ -153,13 +153,46 @@
</para>
<sect3>
<title>
sgmltools
Jade
</title>
<para>
Required
Required - <ulink url="ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz">ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz</ulink>
</para>
<para>
The sgmltools package contains the SGML tools needed to render SGML as any of the file formats listed above. It also contains the LinuxDoc DTD, needed to make LDP documentation. To create only SGML documentation, this is all you need. If you want to render to formats like TeX, you'll need to get those packages as well. The sgmltools package is available either with your distribution of choice, or via http://www.sgmltools.org/. Note that you will need version 1.0.9 to use LinuxDoc. Any other version is written for DocBook.
Jade is the front-end processor for SGML. It uses the DSSSL and DocBook DTD to perform the verification and rendering from SGML into the target format.
</para>
</sect3>
<sect3>
<title>
DSSSL
</title>
<para>
Required - <ulink url="http://nwalsh.com/docbook/dsssl/db152.zip">http://nwalsh.com/docbook/dsssl/db152.zip</ulink>
</para>
<para>
The Document Style Semantics and Specification Language tells jade how to render a SGML document into print or online form. The DSSSL is what converts a title tag into an &lt;H1&gt; tag in HTML, or bold, 14 point Times Roman for RTF, for example. Documentation for DSSSL is located at <ulink url="http://nwalsh.com/docbook/dsssl/db152d.zip">http://nwalsh.com/docbook/dsssl/db152d.zip</ulink>. Note that modifying the DSSSL doesn't modify DocBook itself. It merely changes the way the rendered text looks. The LDP uses a modified DSSSL that provides for a table of contents.
</para>
</sect3>
<sect3>
<title>
DocBook DTD (version 3.1)
</title>
<para>
Required - <ulink url="http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip">http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip</ulink>
</para>
<para>
The DocBook DTD defines the tags and structure of a DocBook SGML document. Modifying the DTD, such as adding a new tag, doesn't make it DocBook anymore.
</para>
</sect3>
<sect3>
<title>
sgmltools-lite
</title>
<para>
Highly Recommended - <ulink url="http://sgmltools-lite.sourceforge.net/">http://sgmltools-lite.sourceforge.net/</ulink>
</para>
<para>
This is the successor to the sgmltools project, which has officially been disbanded for over a year. Since then, Cees de Groot has created a slightly different project, which acts as a wrapper to the jade SGML processor. It hides much of the ugliness of syntax. This author was able to install the old sgmltools package followed by the sgmltools-lite and could format this document quite easily. There's even a man page for sgmltools showing syntax.
</para>
</sect3>
<sect3>
@ -178,10 +211,10 @@
LyX
</title>
<para>
Optional
Optional - <ulink url="http://www.lyx.org/">http://www.lyx.org/</ulink>
</para>
<para>
The LyX program is a graphical WYSIWYM (What You See Is What You Mean) and provides a much-needed link between an easy-to-use graphical app and renderer and the sometimes-complex rules of SGML. LyX was really used to write TeX documentation, and many of the TeX rules apply in LyX. For example, while sections are automatically numbered, you can't insert whitespace (spaces and tabs) easily. It's against what TeX was designed to do. As it is, SGML often ignore the same whitespace. The LyX program can read the LinuxDoc DTD and provide a template document for you to write (or edit) your LDP documentation in a way that you're familiar with, without having to use vi and remember what the tags are for itemizing a list. LyX is available at http://www.lyx.org/. For those of you using KDE, there is a port of LyX using the Qt libraries. You can find more information on this version at http://www.devel.lyx.org/&tilde;ettrich/klyx.html.
LyX provides the power of writing SGML with the ease-of-use of a regular word processor. It's not a WYSIWYG program, but more WYSIWYM (What You See Is What You Mean) application, since what you see on the screen isn't necessarily what happens after the SGML processor is done with it.
</para>
</sect3>
<sect3>
@ -189,10 +222,10 @@
Emacs (PSGML)
</title>
<para>
Optional
Optional - <ulink url="http://www.lysator.liu.se/~lenst/about_psgml/">http://www.lysator.liu.se/~lenst/about_psgml/</ulink>
</para>
<para>
There is an Emacs mode for writing SGML and XML documents. You can get more information about it at <ulink url="http://www.lysator.liu.se/projects/about_psgml.html">http://www.lysator.liu.se/projects/about_psgml.html</ulink>.
Emacs has an SGML writing mode called psgml. Anyone with experience writing in this mode is welcome to e-mail the author of this document. psgml is a major mode in Emacs designed for editing SGML and XML documents. It provides &quot;syntax highlighting&quot; or &quot;pretty printing&quot; features that make SGML tag stand out, a way to insert &quot;tags&quot; other than typing them by hand, and the ability to validate your document while writing. For users of Emacs, it's a great way to go, and many believe it to allow more versatility than any other SGML documentation tool. It works with DocBook, LinuxDoc and other DTDs equally well.
</para>
</sect3>
<sect3>
@ -200,10 +233,10 @@
WordPerfect 2000
</title>
<para>
Optional
Not recommended - <ulink url="http://www.corel.com/">http://www.corel.com/</ulink>
</para>
<para>
The latest release of WordPerfect 2000 will have support for SGML modes. I'm not sure yet if this includes LinuxDoc, or only DocBook. If you're a beta tester of WP2k and can tell me how well it works, I'll be happy to include your notes.
WordPerfect 2000 for the MS Windows platform has limited support for SGML and DocBook 3.0. WordPerfect 2000 for Linux has no SGML capabilities.
</para>
</sect3>
<sect3>
@ -211,10 +244,21 @@
DocBook: The Definitive Guide
</title>
<para>
Optional (but recommended)
Optional (but recommended) - <ulink url="http://www.docbook.org/">http://www.docbook.org/</ulink>
</para>
<para>
This book was released by O'Reilly in October 1999, and is a great reference to DocBook. I have not found it to be a great practical book, and much of the emphasis is on XML, but the DocBook tags for version 3.1 are all listed in a handy format. You can pick it up at the book vendor of choice, or see the entire thing online at http://www.docbook.org.
This book was released by O'Reilly in October 1999, and is a great reference to DocBook. I have not found it to be a great practical book, and much of the emphasis is on XML, but the DocBook tags for version 3.1 are all listed in a handy format. You can pick it up at the book vendor of choice. The entire book is also available online at the above URL.
</para>
</sect3>
<sect3>
<title>
Aspell
</title>
<para>
Optional - <ulink url="http://aspell.sourceforge.net/">http://aspell.sourceforge.net/</ulink>
</para>
<para>
This spell checking application can work around SGML tags, and only spell check the content within the tags. Default spell checkers like ispell will try to spellcheck the tags, causing errors at every new tag.
</para>
</sect3>
</sect2>
@ -224,14 +268,14 @@
Getting Started with DocBook
</title>
<para>
This section covers the new method of writing LDP documentation, using the DocBook 3.1 DTD. We'll cover getting, installing, and using tools, along with an introduction to DocBook tags. Since there are over 300 DocBook tags, we won't cover them all here. Really interested readers can go to http://www.docbook.org for more information.
This section covers the new method of writing LDP documentation, using the DocBook 3.1 DTD. We'll cover getting, installing, and using tools, along with an introduction to DocBook tags. Since there are over 300 DocBook tags, we won't cover them all here. Really interested readers can go to http://www.docbook.org for more information.
</para>
<sect2>
<title>
For New Authors
</title>
<para>
If you are a new to the LDP and want to pick up an unmaintained HOWTO or write a new HOWTO or mini-HOWTO document, contact the HOWTO coordinator at <ulink url="mailto:ldp-discuss@lists.linuxdoc.org">ldp-discuss@lists.linuxdoc.org</ulink>. This is to make sure the HOWTO coordinator can know who is working on what documentation. Also note that all HOWTO submissions must be in SGML format (using DocBook or LinuxDoc DTD). The mini-HOWTO submissions may be made in either SGML or HTML formats, but only SGML-formatted submissions will be included in printed versions of the HOWTOs.
If you are a new to the LDP and want to pick up an unmaintained HOWTO or write a new HOWTO or mini-HOWTO document, contact the HOWTO coordinator at <ulink url="mailto:ldp-discuss@lists.linuxdoc.org">ldp-discuss@lists.linuxdoc.org</ulink>. This is to make sure the HOWTO coordinator can know who is working on what documentation. Also note that all HOWTO submissions must be in SGML format using the DocBook 3.1 DTD. The mini-HOWTO submissions may be made in either SGML or HTML formats, but only SGML-formatted submissions will be included in printed versions of the HOWTOs.
</para>
</sect2>
<sect2>
@ -286,6 +330,48 @@ make install
Must of this is covered by Jorge Godoy's Using DocBook document. Those interested can read it at <ulink url="http://metalab.unc.edu/godoy/using-docbook/using-docbook.html">http://metalab.unc.edu/godoy/using-docbook/using-docbook.html</ulink> for writing DocBook using your favorite text editor.
</para>
</sect2>
<sect2>
<title>
Writing SGML using LyX
</title>
<sect3>
<title>
New documents
</title>
<para>
You can easily start a new HOWTO using LyX. Use the <emphasis>File-&gt;New from template... </emphasis>menu command to bring up the template listings. Select <emphasis>Templates</emphasis> on the right side of the screen, then select <emphasis>docbook_template.lyx</emphasis> in the file listing. Select OK, and you'll have a new document. Fill in the items, such as title, abstract, and author name, then start writing.
</para>
</sect3>
<sect3>
<title>
Existing documents
</title>
<para>
If you have an already-existing LyX, TeX, or text document, you can import it into LyX with the <emphasis>File-&gt;import</emphasis> command. Once the file is imported, go to <emphasis>Layout-&gt;Document...</emphasis> In the popup window, under Style, select <emphasis>SGML (DocBook Article)</emphasis>. You'll be asked if you want to convert all text over, and say Yes. You will need to reapply most tags, but it's a fairly simple matter of selecting text and changing the style. Many LyX functions have a keyboard shortcut to assist you.
</para>
</sect3>
<sect3>
<title>
Exporting documents to SGML
</title>
<para>
Once your document is written or converted, save it in LyX format. This will allow you to edit future versions easily. Then, go to <emphasis>File-&gt;Export-&gt;as DocBook...</emphasis> and the file will be exported in DocBook.
</para>
</sect3>
</sect2>
<sect2>
<title>
Writing SGML using PSGML
</title>
<sect3>
<title>
Not written
</title>
<para>
Unfortunately, I don't use Emacs. If you use PSGML for writing/validating SGML, please e-mail the author your directions and I'll be happy to add them here as a service for other users.
</para>
</sect3>
</sect2>
</sect1>
<sect1>
<title>
@ -562,36 +648,7 @@ make install
</sect1>
<sect1>
<title>
Writing SGML using other tools
</title>
<sect2>
<title>
LyX
</title>
<para>
I'm still gushing about LyX. Okay, so I'm a bit biased towards this application because I really like it. It provides the power of writing SGML with the ease-of-use of a regular word processor. It's not a WYSIWYG program, but more WYSIWYM (What You Get Is What You Mean) application, since what you see on the screen isn't necessarily what happens after the SGML processor is done with it. To create a LinuxDoc document with LyX, download and install the application. Make sure you have TeX and sgmltools installed first (see the section called The tools (Installing the Tools) for more information on this). Once complete, start up LyX and select &quot;file-&gt;new from template...&quot; Select &quot;Templates&quot; then click on linuxdoctemplate.lyx and you'll have a template document set up, with most of the header information that an LDP document should have. Change the data to suit your need (that is, fill in the Title, Author, Date, Abstract, and so on) and then start writing. The pull down menu in the upper left hand corner can be used to select types of content (standard, itemized and enumerated lists, sections). The exclamation point is used to emphasize text, and you can either click it and begin typing in emphasized mode, or highlight text with the mouse and click on it to emphasize the highlighted text. Many other features of SGML can be found under the Insert menu bar. You can insert URL locations, cross references, index entries, and other kinds of data. When complete with your documentation, you can save it in LyX format, then export to LinuxDoc and have the file saved with a .sgml extension. That file is then ready to be checked with sgmlcheck and rendered to the formats you want.
</para>
</sect2>
<sect2>
<title>
Emacs
</title>
<para>
Emacs has an SGML writing mode called psgml. Anyone with experience writing in this mode is welcome to e-mail the author of this document. psgml is a major mode in Emacs designed for editing SGML and XML documents. It provides &quot;syntax highlighting&quot; or &quot;pretty printing&quot; features that make SGML tag stand out, a way to insert &quot;tags&quot; other than typing them by hand, and the ability to validate your document while writing. For users of Emacs, it's a great way to go, I believe it to allow more versatility than any other SGML documentation tool. It works with DocBook, LinuxDoc and other DTDs equally well. The documentation for psgmls can be found at <ulink url="http://www.lysator.liu.se/~lenst/about_psgml/">http://www.lysator.liu.se/~lenst/about_psgml/</ulink>
</para>
</sect2>
<sect2>
<title>
Other SGML tools
</title>
<para>
If there are other SGML tools out there, please let me know.
</para>
</sect2>
</sect1>
<sect1>
<title>
CVS basics
CVS
</title>
<para>
The LDP is in the process of providing CVS access to authors. There are a few good reasons for using CVS:
@ -624,12 +681,12 @@ make install
<itemizedlist>
<listitem>
<para>
http://www.sourcegear.com/CVS/Docs/blandy
<ulink url="http://www.sourcegear.com/CVS/Docs/blandy">http://www.sourcegear.com/CVS/Docs/blandy</ulink>
</para>
</listitem>
<listitem>
<para>
https://wroclaw.art.pl/&tilde;ser/docs/cvs.html
<ulink url="https://wroclaw.art.pl/~ser/docs/cvs.html">https://wroclaw.art.pl/~ser/docs/cvs.html</ulink>
</para>
</listitem>
</itemizedlist>
@ -696,7 +753,7 @@ $ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login
CVS Files via web
</title>
<para>
You can access the CVS repository via the web at http://cvsweb.linuxdoc.org/index.cgi/linuxdoc.
You can access the CVS repository via the web at <ulink url="http://cvsweb.linuxdoc.org/index.cgi/linuxdoc">http://cvsweb.linuxdoc.org/index.cgi/linuxdoc</ulink>.
</para>
</sect3>
<sect3>
@ -704,7 +761,7 @@ $ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login
Graphical access to CVS
</title>
<para>
There are graphical interfaces to CVS, and you can get a list of them at http://freshmeat.net/appindex/. Search for CVS.
There are graphical interfaces to CVS, and you can get a list of them at <ulink url="http://freshmeat.net/appindex">http://freshmeat.net/appindex</ulink>. Search for CVS.
</para>
</sect3>
</sect2>
@ -713,10 +770,10 @@ $ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login
Updating files and CVS
</title>
<para>
CVS has a special tag that you can use to automatically insert the date and version directly into the document. This is called &dollar;Id&dollar;. By including this tag in (for example) your &lt;date&gt; tag, you can have that automatically change each time you change the file, allowing the revision mark to increment each time.
CVS has a special tag that you can use to automatically insert the date and version directly into the document. This is called <emphasis>&dollar;Id&dollar;</emphasis>. By including this tag in your document, you can have that automatically change each time you change the file, allowing the revision mark to increment each time.
</para>
<para>
When you're ready to upload changes to the CVS server, use the command cvs ci -m &quot;comment&quot; YOUR-HOWTO.sgml. The -m &quot;comment&quot; isn't necessary, but if you don't include it, you'll be brought into the editor (usually vi, or whatever your EDITOR environment varialbe is) and be given the chance to add a comment about the changes.
When you're ready to upload changes to the CVS server, use the command <emphasis>cvs ci -m &quot;comment&quot; YOUR-HOWTO.sgml</emphasis>. The -m &quot;comment&quot; isn't necessary, but if you don't include it, you'll be brought into the editor (usually vi, or whatever your EDITOR environment variable is) and be given the chance to add a comment about the changes.
</para>
<para>
You can follow more of the CVS discussion on the ldp-discuss list. For the time being, LDP submissions should still be sent to ldp-submit.
@ -735,7 +792,7 @@ $ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login
Before you distribute your code to millions of potential readers there are a few things you should do.
</para>
<para>
First, be sure to spell-check your document. Most utilities that you would use to write SGML (emacs, LyX, other text editors) have plug-ins to perform a spell check. If not, there's always the ispell program, installed in just about every distribution. Also use the sgmlcheck command with sgmltools to verify you have correct SGML tags.
First, be sure to spell-check your document. Most utilities that you would use to write SGML have plug-ins to perform a spell check. If not, there's always the aspell program.
</para>
<para>
Second, get someone to review your documentation for comments and factual correctness. The documentation that is published by the LDP needs to be as factually correct as possible, as there are millions of Linux users that may be reading it. If you're part of a larger mailing list talking about the subject, ask others from the list to help you out.
@ -743,6 +800,20 @@ $ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login
<para>
Third, create a web site where you can distribute your documentation. This isn't required, but is helpful for people to find the original location of your document.
</para>
<sect3>
<title>
Validate your SGML code
</title>
<para>
Using sgmltools, or really the nsgmls command, you can validate your .sgml code against the DTD to make sure there aren't any errors.
</para>
<programlisting>
nsgmls -s HOWTO-HOWTO.sgml
</programlisting>
<para>
If there are no issues, you'll just get your command prompt back.
</para>
</sect3>
</sect2>
<sect2>
<title>
@ -757,10 +828,10 @@ $ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login
Submission to LDP
</title>
<para>
Once your LDP document has been reviewed by a few people and you took into account their comments, you can release your document to the LDP in general. Send an e-mail with the SGML source code (you may gzip it if you like) to <ulink url="mailto:ldp-submit@lists.linuxdoc.org">ldp-submit@lists.linuxdoc.org</ulink>.
Once your LDP document has been reviewed by a few people and you took into account their comments, you can release your document to the LDP. Send an e-mail with the SGML source code as an attachment (you may gzip it if you like) to <ulink url="mailto:ldp-submit@lists.linuxdoc.org">ldp-submit@lists.linuxdoc.org</ulink>.
</para>
<para>
Be sure to include the name of your HOWTO in the subject line, and use the body to outline changes you've made and attach your HOWTO. This allows the maintainers to do their jobs faster, so you don't have to wait for your HOWTO to be updated on the LDP website. If you don't hear anything in 7 calendar days, please follow up with an e-mail to make sure things are still in process.
Be sure to include the name of your HOWTO in the subject line, and use the body to outline changes you've made and attach your HOWTO. This allows the maintainers to do their jobs faster, so you don't have to wait for your HOWTO to be updated on the LDP web site. If you don't hear anything in 7 calendar days, please follow up with an e-mail to make sure things are still in process.
</para>
</sect2>
<sect2>
@ -768,28 +839,19 @@ $ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login
Style guides
</title>
<para>
This isn't a hard and fast guide on writing good documentation (yet), but consider it a bunch of hints to help you along as you write.
This section contains notes on conventions that the LDP has agreed to in order to give all LDP documents a similar look and feel. You should keep these guides in mind when writing.
</para>
<itemizedlist>
<listitem>
<sect3>
<title>
Date formats
</title>
<para>
Be clear. Everyone needs to know what you're talking about.
The &lt;date&gt; tag in your header should be in the following format:
</para>
</listitem>
<listitem>
<para>
Use examples where possible. It lets everyone see what you're talking about.
</para>
</listitem>
<listitem>
<para>
Organize. Don't jump between unrelated topics in the same section.
</para>
</listitem>
</itemizedlist>
<para>
You can get many more hints from the LDP style guide located at http://www.linuxdoc.org/HOWTO/LDP-Style-Guide.html.
</para>
<programlisting>
v1.0, 21 April 2000
</programlisting>
</sect3>
</sect2>
</sect1>
<sect1>
@ -824,3 +886,4 @@ $ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login
</article>

311
LDP/howto/linuxdoc/PalmOS-HOWTO.sgml
View File

@ -8,7 +8,7 @@
<title>Palm OS Desktop HOWTO
<author>by David H. Silber
<tt><htmlurl url="mailto:palm@orbits.com" name="palm@orbits.com"></tt>
<date>v1.0.0, 20 September 1998
<date>v1.1.1, 28 February 1999
<abstract>
This HOWTO document explains how to use your Palm OS device with a
Linux system.
@ -22,27 +22,42 @@ operating system, this one is not dependent on the version of unix used.
<sect>Introduction
<p>
First there was the Pilot, then the PalmPilot, and now we have the
Palm III from Palm Computing Devices.
IBM sells a rebadged version of the PalmPilot Professional, which they
call the WorkPad.
PalmOS is the operating system used by the Pilot, PalmPilot, WorkPad,
Palm III, Palm IIIx, Palm V, and pdQ smartphone devices.
Each of these gadgets is a Personal Digital Assistant (PDA) and
comes with programs to help the user keep track of personal information,
such as addresses &amp; telephone numbers, meetings, todo lists and
general notes.
In this way, they replace the traditional paper address book, calendar
and notepad.
PalmOS devices improve on earlier PDAs in that they can synchronize their
data with another computer.
Of course the other computer must have compatible software in order to
communicate with the PalmOS device.
This software is often referred to as a <em>conduit</em>.
Although
<htmlurl url="http://www.3com.com/" name="3Com">
does not support Linux conduits, Linux developers have provided a
wide variety of applications which share data with PalmOS devices.
<!--
What are these gadgets?
They are Personal Digital Assistants (PDAs), sometimes known as palm-top
computers.
Sold as an electronic combination of address book, telephone directory
and memo pad, they are actually general-purpose computers capable of
running almost any kind of application.
The trick is to find Palm OS applications to fit your needs and to be
able to share your data with your Linux system.
These particular PDAs are alike in that they use the Palm Operating
System, or <em>PalmOS</em>
Palm OS devices incorporate software to synchronize their data with
programs running on another computer.
Such software for use on a Windows 95 system is generally bundled with
the device.
A MacOS version is also available.
If the foriegn computer is running some other operating system, you
need to find third party software to work with your Palm OS device.
The trick is to find Palm OS applications to fit your needs and to be
able to share your data with your Linux system.
This document describes such software that is available for use on a
Linux or unix system.
-->
<!--
<sect1>What is a Pilot?
@ -73,8 +88,7 @@ to be loaded onto the PDA from another computer.
The latest version of this document can be read at
<tt><htmlurl url="http://www.orbits.com/Palm/PalmOS-HOWTO.html"
name="http://www.orbits.com/Palm/PalmOS-HOWTO.html"></tt>,
and is part of the
Linux Documentation Project (LDP).
and is part of the Linux Documentation Project (LDP).
This document superceedes the previous version, which was called the
<tt>Pilot HOWTO</tt>.
See
@ -86,7 +100,7 @@ If you find anything in this document which needs to be corrected or
better explained, please send me e-mail at the address above and
specify which version of this document you are referring to.
This document is Copyright &copy; 1997 &amp; 1998 by David H. Silber.
This document is Copyright &copy; 1997, 1998 &amp; 1999 by David H. Silber.
It is released under the copyright terms in the LDP HOWTO-INDEX document.
<sect1>See Also
@ -103,45 +117,10 @@ name="http://www.orbits.com/Palm/PalmConduit-HOWTO.html"></tt>
document describes how to use the pilot-link libraries to write
Linux-resident conduits for use with Palm OS devices.
<sect1>Mailing List<label id="pilot-unix">
<p>
The pilot-unix mailing list is maintained by
Matthew Cravit
<htmlurl url="mailto:pilot-unix-owner@lists.best.com"
name="pilot-unix-owner@lists.best.com">.
Its mandate is:
<tscreen><verb>
The pilot-unix mailing list is for discussion and idea-sharing for those
interested in using the US Robotics Pilot PDAs with UNIX systems. This
includes people who are interested in helping to develop tools to allow the
Pilot to operate with UNIX, and possibly to develop an SDK for the Pilot
for Unix.
</verb></tscreen>
For more information, including how to subscribe to the list, send
mail containing the word ``<tt>INFO</tt>''
to <tt><htmlurl url="mailto:pilot-unix-request@lists.best.com"
name="pilot-unix-request@lists.best.com"></tt>.
The subject line does not matter.
<sect1>Mailing List Archives<label id="pilot-unix-archives">
<p>
An archive of the pilot-unix mailing list can be found at
<tt><htmlurl url="http:///www.acm.rpi.edu/&tilde;albert/pilot/"
name="http:///www.acm.rpi.edu/&tilde;albert/pilot/"></tt>.
It is maintained by Chris Stevens
<htmlurl url="mailto:albert@acm.rpi.edu" name="albert@acm.rpi.edu">.
<sect1>FTP Site<label id="pilot-unix-ftp-site">
<p>
An FTP site containing an archive of Palm OS tools for use on unix systems
is located at
<tt><htmlurl url="ftp://ryeham.ee.ryerson.ca/pub/PalmOS/"
name="ftp://ryeham.ee.ryerson.ca/pub/PalmOS/"></tt>.
It is maintained by Jeff Dionne
<htmlurl name="jeff@ryeham.ee.ryerson.ca"
url="mailto:jeff@ryeham.ee.ryerson.ca">.
You may also wish to look at
<tt><htmlurl url="http://www.orbits.com/Palm/"
name="http://www.orbits.com/Palm/"></tt>
for updates on the status of these and related documents.
<sect>General Information
@ -164,9 +143,9 @@ will be an alternate name for the serial port to which your Palm OS device
cradle is connected.
As the root user, enter the following at the shell prompt:
<tscreen><verb>
ln /dev/cua0 /dev/pilot
ln /dev/ttyS0 /dev/pilot
</verb></tscreen>
Replace <tt>cua0</tt> with the name of the port to which you connected
Replace <tt>ttyS0</tt> with the name of the port to which you connected
your Palm OS device's cradle.
<!--
@ -193,7 +172,12 @@ based on there already being a method of transferring data.
<sect>Sharing Palm OS device Data with your Linux System
<!--
<sect>Sharing Data Between Your Palm OS Device and Linux System
-->
<sect>Sharing Data Between Palm OS and Linux Systems
<sect1>The pilot-link software
<p>
The pilot-link suite of software tools allows you to download
@ -225,9 +209,6 @@ You can get the <it>Debian Linux</it> (i386) port of
<tt><htmlurl
url="ftp://ftp.debian.org/pub/debian/dists/stable/main/binary-i386/otherosfs/pilot-link_0.8.7-2.deb"
name="ftp://ftp.debian.org/pub/debian/dists/stable/main/binary-i386/otherosfs/pilot-link_0.8.7-2.deb"></tt>.
<tt><htmlurl
url="ftp://ftp.debian.org/pub/debian/dists/stable/main/binary-i386/otherosfs/pilot-link&lowbar;0.8.7-2.deb"
name="ftp://ftp.debian.org/pub/debian/dists/stable/main/binary-i386/otherosfs/pilot-link&lowbar;0.8.7-2.deb"></tt>.
If this file does not exist, you will likely find a newer version located
in the same directory.
If all else fails, or if you want a more recent version than has been
@ -500,79 +481,72 @@ FIX-ME: I am not sure exactly what this program does.
FIX-ME: I am not sure exactly what this program does.
-->
<sect1>MakeDoc
<sect2>Mailing List<label id="pilot-unix">
<p>
One short-coming of the Palm OS device's built-in memo program is that it
does not deal well with large documents.
To compensate for this,
<url url="mailto:rbram@concentric.net" name="Rick Bram"> wrote
<it>Doc</it>, a document reader for the Palm OS device.
(See <tt><htmlurl url="http://www.concentric.net/&tilde;rbram/doc.shtml"
name="http://www.concentric.net/&tilde;rbram/doc.shtml"></tt>).
<!--
% There is also <url url="http://" name="Jdoc">, written by
% <url url="mailto:" name="FIX-ME:"> which provides a similar
% functionality, but with a different set of features.
% Both of these programs use documents in the same format.
-->
Documents can be converted to the Doc format with <tt>MakeDoc</tt>,
by <url url="mailto:pat.beirne@sympatico.ca" name="Pat Beirne">.
<sect2>Installing MakeDoc
<p>
<tt>MakeDoc</tt> can be downloaded from
<tt><htmlurl url="http://www.concentric.net/&tilde;rbram/makedoc7.cpp"
name="http://www.concentric.net/&tilde;rbram/makedoc7.cpp"></tt>.
Compile it with your C++ compiler and install the resulting executable
as ``<tt>makedoc</tt>'' in a directory in your search path.
There seems to be a small bug in <tt>makedoc</tt> (version 0.7a) in
that it does not output a newline as the last character displayed to
the user.
This does not seem to affect the resulting document file, but it is
annoying.
<!--
Perhaps I will fix this if I get a chance.
-->
There is a new version out, but it requires Java.
Take a look at Pat Beirne's MakeDoc web page at
<tt><htmlurl url="http://cpu563.adsl.sympatico.ca/MakeDocJ.htm"
name="http://cpu563.adsl.sympatico.ca/MakeDocJ.htm"></tt>.
<sect2>Using MakeDoc
<p>
Use <tt>MakeDoc</tt> as follows:
The pilot-unix mailing list is maintained by
Matthew Cravit
<htmlurl url="mailto:pilot-unix-owner@lists.best.com"
name="pilot-unix-owner@lists.best.com">.
Its mandate is:
<tscreen><verb>
makedoc data.txt data.prc "Data to display with Doc"
The pilot-unix mailing list is for discussion and idea-sharing for those
interested in using the US Robotics Pilot PDAs with UNIX systems. This
includes people who are interested in helping to develop tools to allow the
Pilot to operate with UNIX, and possibly to develop an SDK for the Pilot
for Unix.
</verb></tscreen>
This will create a file <tt>data.prc</tt>, which can be installed
on your Palm OS device with
For more information, including how to subscribe to the list, send
mail containing the word ``<tt>INFO</tt>''
to <tt><htmlurl url="mailto:pilot-unix-request@lists.best.com"
name="pilot-unix-request@lists.best.com"></tt>.
The subject line does not matter.
<sect2>Mailing List Archives<label id="pilot-unix-archives">
<p>
An archive of the pilot-unix mailing list can be found at
<tt><htmlurl url="http:///www.acm.rpi.edu/&tilde;albert/pilot/"
name="http:///www.acm.rpi.edu/&tilde;albert/pilot/"></tt>.
It is maintained by Chris Stevens
<htmlurl url="mailto:albert@acm.rpi.edu" name="albert@acm.rpi.edu">.
<sect2>FTP Site<label id="pilot-unix-ftp-site">
<p>
An FTP site containing an archive of Palm OS tools for use on unix systems
is located at
<tt><htmlurl url="ftp://ryeham.ee.ryerson.ca/pub/PalmOS/"
name="ftp://ryeham.ee.ryerson.ca/pub/PalmOS/"></tt>.
It is maintained by Jeff Dionne
<htmlurl name="jeff@ryeham.ee.ryerson.ca"
url="mailto:jeff@ryeham.ee.ryerson.ca">.
<!--
<ref id="pilot-xfer" name="pilot-xfer">.
<sect>Linux Desktop Synchronization Managers.
-->
pilot-xfer.
The text <it>"Data to display with Doc"</it> will be displayed in the
directory of documents that <it>Doc</it> manages.
The syntax for <tt>MakeDoc</tt> is as follows:
<tscreen><verb>
makedoc [-n] [-b] <text-file> <prc-file> <story-name>
or
makedoc -d [-b] <prc-file> <text-file>
</verb></tscreen>
<descrip>
<tag/&lt;text-file&gt;/The file that you wish to convert.
<tag/&lt;prc-file&gt;/The name of the resulting file. (End the name
with ``<tt>.prc</tt>''.)
<tag/&lt;story-name&gt;/The name you want displayed in the <tt>Doc</tt>
or <tt>Jdoc</tt> directory of documents.
</descrip>
There are also options to decode the resulting <tt>.prc</tt> file
and manage various compression options.
<sect>Linux Applications Which Synchronise with PalmOS Devices.
<sect1>XNotesPlus<label id="XNotesPlus">
<p>
<tt>XNotesPlus</tt> provides a means to post small notes on your
X-Windows desktop.
These notes can be shared as memos with your PalmOS device.
<sect2>Installing XNotesPlus
<p>
The XNotesPlus web page at
<htmlurl url="http://www.graphics-muse.org/xnotes/xnotes.html"
name="http://www.graphics-muse.org/xnotes/xnotes.html">
contains full installation and use instructions.
I suggest using the prebuilt binaries if you can.
One caveat is that you need to create an ``Xnotes'' category on your
PalmOS device, if you intend to export notes.
<!--
@ -664,6 +638,82 @@ This is a wonderful application.
<sect1>Web sites of interest
-->
<sect>Data Conversion
<sect1>MakeDoc
<p>
One short-coming of the Palm OS device's built-in memo program is that it
does not deal well with large documents.
To compensate for this,
<url url="mailto:rbram@concentric.net" name="Rick Bram"> wrote
<it>Doc</it>, a document reader for the Palm OS device.
(See <tt><htmlurl url="http://www.concentric.net/&tilde;rbram/doc.shtml"
name="http://www.concentric.net/&tilde;rbram/doc.shtml"></tt>).
<!--
% There is also <url url="http://" name="Jdoc">, written by
% <url url="mailto:" name="FIX-ME:"> which provides a similar
% functionality, but with a different set of features.
% Both of these programs use documents in the same format.
-->
Documents can be converted to the Doc format with <tt>MakeDoc</tt>,
by <url url="mailto:pat.beirne@sympatico.ca" name="Pat Beirne">.
<sect2>Installing MakeDoc
<p>
<tt>MakeDoc</tt> can be downloaded from
<tt><htmlurl url="http://www.concentric.net/&tilde;rbram/makedoc7.cpp"
name="http://www.concentric.net/&tilde;rbram/makedoc7.cpp"></tt>.
Compile it with your C++ compiler and install the resulting executable
as ``<tt>makedoc</tt>'' in a directory in your search path.
There seems to be a small bug in <tt>makedoc</tt> (version 0.7a) in
that it does not output a newline as the last character displayed to
the user.
This does not seem to affect the resulting document file, but it is
annoying.
<!--
Perhaps I will fix this if I get a chance.
-->
<!-- (Site gone away.)
There is a new version out, but it requires Java.
Take a look at Pat Beirne's MakeDoc web page at
<tt><htmlurl url="http://cpu563.adsl.sympatico.ca/MakeDocJ.htm"
name="http://cpu563.adsl.sympatico.ca/MakeDocJ.htm"></tt>.
-->
<sect2>Using MakeDoc
<p>
Use <tt>MakeDoc</tt> as follows:
<tscreen><verb>
makedoc data.txt data.prc "Data to display with Doc"
</verb></tscreen>
This will create a file <tt>data.prc</tt>, which can be installed
on your Palm OS device with
<!--
<ref id="pilot-xfer" name="pilot-xfer">.
-->
pilot-xfer.
The text <it>"Data to display with Doc"</it> will be displayed in the
directory of documents that <it>Doc</it> manages.
The syntax for <tt>MakeDoc</tt> is as follows:
<tscreen><verb>
makedoc [-n] [-b] <text-file> <prc-file> <story-name>
or
makedoc -d [-b] <prc-file> <text-file>
</verb></tscreen>
<descrip>
<tag/&lt;text-file&gt;/The file that you wish to convert.
<tag/&lt;prc-file&gt;/The name of the resulting file. (End the name
with ``<tt>.prc</tt>''.)
<tag/&lt;story-name&gt;/The name you want displayed in the <tt>Doc</tt>
or <tt>Jdoc</tt> directory of documents.
</descrip>
There are also options to decode the resulting <tt>.prc</tt> file
and manage various compression options.
<appendix>
<sect>People
@ -722,12 +772,17 @@ They also have a backlighting feature for the LCD panel and version
The <it/Professional/ also comes with a TCP/IP stack and a few extra
programs built-in.
(IBM has released a rebadged version of the PalmPilot Professional,
which they call a <it/WorkPad/.)
IBM has released a rebadged version of the PalmPilot Professional,
which they call a <it/WorkPad/.
Now we have the Palm III, which has a redesigned case and an infrared
port, not to mention the 2 Meg of RAM and Palm OS 3.0.
There is an announced product from Qualcomm, called the <it/pdQ smartphone/,
which is a cell phone that incorporates a Palm OS PDA.
Don't get all excited about it yet, it will not be released until sometime
in 1999.
It is possible to upgrade any Pilot by swapping out the memory card,
which includes both RAM &amp; ROM.
Of course, this doesn't get you backlighting for the original Pilot