mirror of https://github.com/tLDP/LDP
These .txt files are notes, you can ignore them. authorguide.2.txt has the
outline I'm working from, if you're interested.
This commit is contained in:
emmajane
parent
33b94ef0a1
commit
451f13127e
|
|
@ -0,0 +1,121 @@
|
|||
THE LINUX DOCUMENTATION PROJECT AUTHOR GUIDE
|
||||
A proposed outline
|
||||
by Emma Jane Hogbin
|
||||
|
||||
ABOUT THE GUIDE
|
||||
About this Guide (1.1)
|
||||
About the LDP (1.2)
|
||||
The LDP (2.1)
|
||||
Feedback [email Mark] (1.3)
|
||||
Copyrights and Trademarks (1.4)
|
||||
Acknowledgments and Thanks (1.5) -- Really should be moved to the end
|
||||
Document Conventions [visual output of various things e.g. warnings] (1.6)
|
||||
|
||||
AUTHORING TLDP DOCUMENTS: AN INTRODUCTION
|
||||
I want to help (section of FAQ, #9)
|
||||
About the process (2.5) [was: For New Authors]
|
||||
Mailing lists (2.6)
|
||||
|
||||
PROPOSE
|
||||
Choosing a subject (5.1)
|
||||
Unmaintained and Out-of-date Documents (NEW)
|
||||
Developing an outline (5.2)
|
||||
Research (NEW)
|
||||
Deciding on a format (see FAQ on different kinds of Docs)
|
||||
|
||||
WRITE
|
||||
The Basics:
|
||||
Write (5.3)
|
||||
Edit and Proofread (5.4) -- add a sub-section on editing
|
||||
unmaintained documents
|
||||
|
||||
For the Slightly More Courageous:
|
||||
LDP Style Guide HOWTO [URLs for sources of technical writing] (5.6)
|
||||
Editing Tools (NEW: gentle intro glean from 3.5 and 5.4)
|
||||
Version Control and CVS (NEW: general intro pointing to CVS Part #2)
|
||||
Other tools/reference [ispell, aspell, docbook definitive guide] (3.7)
|
||||
|
||||
MARKUP
|
||||
DocBook [about SGML] (2.2)
|
||||
Why use DocBook instead of other formats (2.3)
|
||||
Intro to DocBook (4.1)
|
||||
DocBook versions [accepted versions by the LDP] (6.5)
|
||||
Don't know SGML/Don't like (pulled from the FAQ #9)
|
||||
Catalog files gentle intro (NEW -- parts taken from 4.3)
|
||||
DocBook DTD [where to get DTDs] (3.2)
|
||||
|
||||
ELEMENTS AND ATTRIBUTES (THE MARKUP)
|
||||
Writing in DocBook XML [difference between SGML/XML; DocBook 3->4]
|
||||
(2.4) Delete as written--replace with new content
|
||||
Writing DocBook Elements [chart of useful markup] (4.4)
|
||||
Obsolete tags (6.6)
|
||||
Reading a DTD (NEW): parents, children and content models
|
||||
|
||||
ADVANCED MARKUP
|
||||
Images (7.1, 4.6 and 6.4)
|
||||
Indexes (4.5)
|
||||
Tables (4.7)
|
||||
Listings and Program Codes (4.8)
|
||||
|
||||
CONVENTIONS
|
||||
Conventions (6.8)
|
||||
Tag minimization (6.7)
|
||||
Naming separate HTML files (content perspective) (7.2)
|
||||
|
||||
|
||||
DISTRIBUTION AND PUBLISHING
|
||||
Before you distribute [spell check; review; validate; create web site
|
||||
for original doc] (8.1)
|
||||
Copyright and Licensing Issues (8.2)
|
||||
Submission to the LDP [email or email + CVS]
|
||||
Can I publish documents in the LDP? (Pull from FAQ #9)
|
||||
What The LDP does: document transformations (refer to Appendix)
|
||||
|
||||
MAINTENANCE
|
||||
Maintaining your HOWTO (5.5)
|
||||
Maintaining your HOWTO (8.4)
|
||||
Content errors (was in FAQ #9)
|
||||
CVS [maintaining documents; repository notes; recovering old versions
|
||||
etc] (3.6)
|
||||
|
||||
|
||||
|
||||
APPENDIX A. RESOURCES FOR NEW AUTHORS
|
||||
DocBook (2.5.1)
|
||||
Technical Writing (5.6)
|
||||
|
||||
|
||||
APPENDIX B. EDITORS, VALIDATION AND SYSTEM SETUP
|
||||
Editing Tools (reminder from WRITING and point to configuration
|
||||
information in VALID DOCUMENTS AND SYSTEM SETUP)
|
||||
|
||||
VALID DOCUMENTS AND SYSTEM SETUP
|
||||
Configuration needed [exporting SGML_CATALOG_FILES] (4.2)
|
||||
Editing Tools [configuration] (3.5)
|
||||
|
||||
ADVANCED SETUP
|
||||
Creating and modifying catalogs (4.3)
|
||||
|
||||
|
||||
APPENDIX C. TEMPLATES AND DOCUMENT COMPONENTS
|
||||
Revision history (6.2)
|
||||
Date formats (6.1)
|
||||
License (glean from 8.2)
|
||||
Abstract
|
||||
Sample Article (6.3)
|
||||
Document Samples (4.11)
|
||||
LDP Templates, Tools and Links (3.7.2)
|
||||
|
||||
|
||||
APPENDIX D. TRANSFORMATIONS (MAKING HTML OUT OF XML)
|
||||
Crediting translators and converters (4.9)
|
||||
Tools and Hints (4.10)
|
||||
includes: compiling sources, inserting summary on initial article
|
||||
page, inserting indexes, marking notes on text, reusing parts of
|
||||
the document
|
||||
DSSSL (3.1)
|
||||
Jade (3.3)
|
||||
Jade Wrappers (3.4)
|
||||
Naming separate HTML files (transformation HOWTO) (7.2)
|
||||
Using the LDP XSL style sheets (7.4)
|
||||
Using ldp.dsl (7.3)
|
||||
|
|
@ -0,0 +1,115 @@
|
|||
Date: Sun, 20 Jul 2003 15:46:12 -0600
|
||||
From: Charles Curley <charlescurley@charlescurley.com>
|
||||
To: discuss@en.tldp.org
|
||||
Subject: OpenOffice.org 1.1RC & DocBook
|
||||
|
||||
I just hauled in and installed on a test computer OpenOffice.org 1.1RC
|
||||
(hereafter OOo). The Linux is Red Hat 8.0 with security updates. My
|
||||
main interest is in the DocBook export filter, which has seen some
|
||||
discussion on the LDP lists.
|
||||
|
||||
I wrote a very simple test document in OOo's native format. It had
|
||||
some headers and a few paragraphs of text in it. OOo exported what
|
||||
nsgmls considers a valid document.
|
||||
|
||||
nsgmls -wxml -s /usr/share/sgml/xml.dcl Test.xml
|
||||
nsgmls:/usr/share/sgml/xml.dcl:1:W: SGML declaration was not implied
|
||||
|
||||
SGML validation finished at Sun Jul 20 15:10:41
|
||||
|
||||
A few notes:
|
||||
|
||||
* To be able to export to DocBook, you must have a Java runtime
|
||||
environment (JRE) installed and registered with OOo. If you don't
|
||||
already have one installed or have one registered with OOo, you can
|
||||
do that after you have installed OOo. To register a JRE with an
|
||||
installed instance of OOo, shut down OOo and use the program
|
||||
/opt/OpenOffice.org1.1/program/jvmsetup to register it.
|
||||
|
||||
Contrary to the OOo documentation, the Linux OOo did not come with a
|
||||
JRE. I got one from Sun.
|
||||
|
||||
* The exported file has lots of empty lines. My 54 line exported file
|
||||
had 5 lines of actual XML code.
|
||||
|
||||
* There was no effort at pretty printing.
|
||||
|
||||
* The header is:
|
||||
<?xml version=3D"1.0" encoding=3D"UTF-8"?>
|
||||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http:/=
|
||||
/www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
|
||||
|
||||
* The pull-down menu in the "Save As" dialog box for file format
|
||||
indicates that the export format is "DocBook (simplified)." There is
|
||||
no explanation of what that "simplified" indicates. Does OOo export
|
||||
a subset of DocBook? If so, which elements are ignored? Is there any
|
||||
way to enter any of them manually?
|
||||
|
||||
* There is NO documentation on the DocBook export filter or whether
|
||||
OOo will import it again. Tch, tch.
|
||||
|
||||
Conclusions: OOo 1.1RC is worth looking at if you want a word
|
||||
processor for preparing DocBook documents.
|
||||
|
||||
However, I hope they cure the lack of documentation. For one thing, it
|
||||
would be nice to know which native OOo styles map to which DocBook
|
||||
elements. It would also be nice to know how to map one's own OOo
|
||||
styles to DocBook elements.
|
||||
|
||||
--=20
|
||||
|
||||
Charles Curley /"\ ASCII Ribbon Campaign
|
||||
Looking for fine software \ / Respect for open standards
|
||||
and/or writing? X No HTML/RTF in email
|
||||
http://www.charlescurley.com / \ No M$ Word docs in email
|
||||
|
||||
Additional notes:
|
||||
|
||||
Date: Mon, 21 Jul 2003 09:07:14 +0200
|
||||
From: jdd <jdanield@dodin.net>
|
||||
Subject: Re: OpenOffice.org 1.1RC & DocBook
|
||||
To: tabatha@merlinmonroe.com
|
||||
Cc: docbook@en.tldp.org
|
||||
wrong. jre is not installed by default on most Linux distro (of course
|
||||
depends of what you chooses at install) - mostly ooorc needs a very
|
||||
recent jre (at least 4.2.x, better use the very last)
|
||||
|
||||
>>> do that after you have installed OOo. To register a JRE with an
|
||||
>>> installed instance of OOo, shut down OOo and use the program
|
||||
>>> /opt/OpenOffice.org1.1/program/jvmsetup to register it.
|
||||
|
||||
nope (not usefull). try exporting in docbook and ooo asks if you want to
|
||||
register a java jre. gives the root directory (/opt/j2re1.4.2 for me) of
|
||||
your and thats all (needs restarting ooo).
|
||||
|
||||
notice that jre is given by sun in a .bin file which is not an
|
||||
installable one nor a source, but rather only an archive. lauching the
|
||||
files extracts it in the current directory, so I had to go to /opt
|
||||
before launching jre.bin
|
||||
|
||||
registration of jre must be done by any user for his account, however
|
||||
one no more needs to have his own full jre installed as it was in
|
||||
previous ooo releases.
|
||||
|
||||
I tryed with success saveing in docbook, but have not yet the docbook
|
||||
tools installed and so can't test the result (I'm installing these, but
|
||||
need still some time through the net) - vi see many empty lines. the
|
||||
document was very simple for now. more later
|
||||
|
||||
Date: Mon, 21 Jul 2003 15:45:19 -0400
|
||||
From: Greg Ferguson <gferg@sgi.com>
|
||||
Subject: Re: OpenOffice.org 1.1RC & DocBook
|
||||
It doesn't appear to be the "official" simplified docbook DTD. The
|
||||
public identifier doesn't point at the simplified docbook dtd
|
||||
("-//OASIS//DTD Simplified DocBook XML V4.1.2.5//EN"), so
|
||||
I would assume it's probably something of their own making.
|
||||
|
||||
"official" Simplified DocBook:
|
||||
|
||||
http://www.oasis-open.org/docbook/xml/simple/
|
||||
http://www.docbook.org/tdg/simple/en/html/sdocbook.html
|
||||
|
||||
(supposed to be geared for on-the-fly rendering)
|
||||
|
||||
The OpenOffice simplified (or "special" docbook):
|
||||
http://www.chez.com/ebellot/ooo2sdbk/ (march 2002/French document)
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
Date: Wed, 30 Jul 2003 16:57:17 -0600
|
||||
From: Charles Curley <charlescurley@charlescurley.com>
|
||||
Subject: FYI: DocZilla
|
||||
To: discuss@en.tldp.org
|
||||
|
||||
[-- Attachment #1 --]
|
||||
[-- Type: text/plain, Encoding: quoted-printable, Size: 0.9K --]
|
||||
|
||||
Possibly of interest to this crew.
|
||||
|
||||
"DocZilla is a standard Mozilla that contains extra components
|
||||
providing parsing and displaying SGML/XML documents on the fly without
|
||||
a precompilation step.
|
||||
|
||||
Additional features on DocZilla are DocZilla GUI (Graphical User
|
||||
Interface), support for various link types (ID/IDREF and HyTime clinks
|
||||
with nameloc, treeloc, queryloc locators and XLinks), extended
|
||||
searching capabilities, document set and table of content-
|
||||
support. Mozilla as a basis of DocZilla provides support for HTML and
|
||||
CSS, bookmarks, navigation history, SSL (Secure Sockets Layer), etc."
|
||||
|
||||
http://www.doczilla.com/doczilla.html
|
||||
|
||||
Loading…
Reference in New Issue