mirror of https://github.com/tLDP/LDP
446 lines
16 KiB
XML
446 lines
16 KiB
XML
<!--
|
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
|
-->
|
|
<section id="tools-text-editors">
|
|
<title>Text Editors</title>
|
|
|
|
<caution><title>For advanced writers</title><para>
|
|
The tools outlined in this section allow you to work with
|
|
the DocBook tags directly. If you are not comfortable
|
|
working with markup languages you may want to use a word
|
|
processor instead. Word processors that support DocBook
|
|
are described in <xref linkend="tools-word-processors"
|
|
/>.
|
|
</para></caution>
|
|
|
|
<para>
|
|
If you are comfortable working with markup languages and
|
|
text editors, you'll probably want to customize your
|
|
current editor of choice to handle DocBook files. Below
|
|
are some of the more common text editors that can, with
|
|
some tweaking, handle DocBook files.
|
|
</para>
|
|
|
|
|
|
&configure-emacs;
|
|
|
|
<section id="tools-epcEdit">
|
|
<title>epcEdit</title>
|
|
<indexterm><primary>epcEdit</primary></indexterm>
|
|
<indexterm>
|
|
<primary>Editors</primary>
|
|
<secondary>epcEdit</secondary>
|
|
</indexterm>
|
|
<para>
|
|
<ulink url="http://www.tksgml.de/">
|
|
http://www.tksgml.de</ulink>
|
|
</para>
|
|
|
|
<para>
|
|
The <application>epcEdit</application> program allows you to edit XML files.
|
|
It has the advantages of not needing to know <application>Emacs</application> or
|
|
<application>vi</application> before starting, and is cross-platform, working in both
|
|
Windows and Linux. This is a commercial application, and
|
|
pricing can be found at
|
|
<ulink url="http://www.tksgml.de/pricing.html">
|
|
http://www.tksgml.de/pricing.html</ulink>
|
|
</para>
|
|
|
|
<para>
|
|
Along with visual editing, epcEdit will also validate
|
|
documents on loading, and on demand by using the <menuchoice
|
|
moreinfo="none"><guimenu
|
|
moreinfo="none">Document</guimenu><guimenuitem
|
|
moreinfo="none">Validate</guimenuitem></menuchoice>
|
|
command.</para>
|
|
|
|
<!-- replace this figure with one that shows an XML file -->
|
|
<!-- FIXME -->
|
|
<figure>
|
|
<title>epcEdit screen shot</title>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata format="EPS" fileref="sgeditscreenshot.eps"/>
|
|
</imageobject>
|
|
<imageobject>
|
|
<imagedata format="JPG" fileref="sgeditscreenshot.jpg"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>The screen shot of the <application>epcEdit</application>
|
|
program shows a
|
|
tree on the left side that has the document in a
|
|
hierarchy, while the right side shows the document.
|
|
Tags are shown with a gray background.</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</figure>
|
|
</section>
|
|
|
|
<section id="tools-morphoneditor">
|
|
<title>Morphon XML editor</title>
|
|
<para>
|
|
<ulink url="http://www.morphon.com/xmleditor/index.shtml">
|
|
http://www.morphon.com/xmleditor/index.shtml</ulink>
|
|
</para>
|
|
<para>
|
|
This is a commercial application which is currently
|
|
available for free (with an optional user registration).
|
|
It is written in Java, allowing it to run on any platform
|
|
that has a Java Virtual Machine (that is, works in both
|
|
Windows and Linux).
|
|
</para>
|
|
<para>
|
|
On the plus sides of <application>XMLEditor</application> is the left side of the
|
|
screen shows the hierarchy of the document (starting with Book
|
|
and so on). Selecting an item in the list brings you to that
|
|
part of the document so you can edit it. The right part of the
|
|
screen shows the text without any markup or tags being shown.
|
|
If you have external files as ELEMENTS (as the LDP Author Guide
|
|
does), <application>XMLEditor</application> will follow the links and load the files, so
|
|
you always work on the entire work. On the minus side of this,
|
|
you will get errors if a file is missing.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="tools-nedit">
|
|
<title>nedit</title>
|
|
<indexterm><primary>nedit</primary></indexterm>
|
|
<indexterm>
|
|
<primary>Editors</primary>
|
|
<secondary>nedit</secondary>
|
|
</indexterm>
|
|
<para>
|
|
<ulink url="http://nedit.org">
|
|
http://nedit.org</ulink>
|
|
</para>
|
|
|
|
<para>
|
|
To be fair, <application>nedit</application> is more
|
|
for programmers, so it might seem a bit of overkill for new
|
|
users and especially non-programmers. All that aside, it's
|
|
extremely powerful, allowing for syntax highlighting. Unlike
|
|
<application>epcEdit</application>, <application>nedit</application> doesn't allow you to automatically insert tags
|
|
or automatically validate your code. However, it does allow
|
|
for shell commands to be run against the contents of the
|
|
window (as opposed to saving the file, then checking).
|
|
|
|
<!-- TODO replace this screen shot with one that shows an
|
|
XML file instead of an SGML file -->
|
|
<figure>
|
|
<title>nedit screen shot</title>
|
|
<mediaobject>
|
|
<!-- TODO
|
|
Most of the applications could do with fresh screen shots
|
|
using XML files instead of SGML files.
|
|
I've created a new JPG but the EPS no longer matches.
|
|
<imageobject>
|
|
<imagedata fileref="neditscreenshot.eps" format="EPS"/>
|
|
</imageobject> -->
|
|
<imageobject>
|
|
<imagedata fileref="neditscreenshot.jpg" format="JPG"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>The <application>nedit</application> program can provide line numbers
|
|
across the left side of the screen, handy for when
|
|
<command>nsgmls</command> complains of errors</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</figure>
|
|
</para>
|
|
|
|
<section id="usingnedit">
|
|
<title>Using nedit</title>
|
|
<para>When you open your DocBook file, <application>nedit</application> should already
|
|
have syntax highlighting enabled. If it does not you can
|
|
turn it on explicitly using:
|
|
<menuchoice>
|
|
<guimenu>Preferences</guimenu>
|
|
<guimenuitem>Language Mode</guimenuitem>
|
|
<guimenuitem>SGML HTML</guimenuitem>
|
|
</menuchoice>
|
|
</para>
|
|
|
|
<para>
|
|
If you have line numbers turned on (using
|
|
<menuchoice><guimenu>Preferences</guimenu><guimenuitem>Show
|
|
Line Numbers</guimenuitem></menuchoice>) then finding
|
|
validation errors is much simpler.
|
|
<application>nsgmls</application>, the validation tool
|
|
we'll use, lists errors by their line number.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="nedit-scripting">
|
|
<title>Configuring nedit</title>
|
|
<para>
|
|
Since you can feed the contents of your window to
|
|
outside programs, you can easily extend nedit to perform
|
|
repetitive functions. The example you'll see here is to
|
|
validate your document using
|
|
<application>nsgmls</application>.
|
|
For more information about <application>nsgmls</application> and validating
|
|
documents please read <xref linkend="tools-validate" />.
|
|
</para>
|
|
|
|
<!-- Make sure the guimenu markup is consistent and correct. -->
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
Select <menuchoice><guimenu>Preferences</guimenu><guimenuitem>Default
|
|
Settings</guimenuitem><guimenuitem>Customize
|
|
Menus</guimenuitem><guimenuitem>Shell
|
|
Menu...</guimenuitem></menuchoice>. This will bring up the
|
|
Shell Command dialog box, with all the shell commands nedit
|
|
has listed under the
|
|
<menuchoice><guimenu>Shell</guimenu></menuchoice> menu.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Under
|
|
Menu Entry, enter <quote>Validate DocBook.</quote> This will be the entry
|
|
you'll see on the screen.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Under Accelerator, press
|
|
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>.
|
|
Once this menu item is set up, you can press
|
|
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>
|
|
to have the Validate DocBook automatically run.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Under Command
|
|
Input, select window, and under Command Output, select
|
|
dialog.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
Under Command to Execute, enter
|
|
<command>nsgmls
|
|
<parameter>-sv</parameter></command>. Using
|
|
<parameter>-v</parameter> outputs the version number
|
|
is output to the screen so that you know the command
|
|
has run.
|
|
</para>
|
|
<note><title>Check the PATH</title><para>Note
|
|
that <application>nsgmls</application> has to be in your
|
|
<envar>PATH</envar> for this to work properly.
|
|
</para></note>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<figure>
|
|
<title>Adding shell commands to nedit</title>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="neditshellcommand.eps" format="EPS"/>
|
|
</imageobject>
|
|
<imageobject>
|
|
<imagedata fileref="neditshellcommand.jpg" format="JPG"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</figure>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
Click <guibutton>OK</guibutton> and you'll now be back
|
|
at the main nedit screen. Load up an XML file, and select
|
|
<menuchoice><guimenu>Shell</guimenu><guimenuitem>Validate
|
|
DocBook</guimenuitem></menuchoice> or press
|
|
<keycombo><keycap>Alt</keycap><keycap>S</keycap></keycombo>.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
The <command>nedit</command> program will fire up and check
|
|
the contents of the window.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
If all you see is a version number for
|
|
<application>nsgml</application> then your
|
|
document is valid. Any errors are reported by line
|
|
number in your document.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<figure>
|
|
<title><application>nsgmls</application> output on success</title>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="neditsuccess.eps" format="EPS"/>
|
|
</imageobject>
|
|
<imageobject>
|
|
<imagedata fileref="neditsuccess.jpg" format="JPG"/>
|
|
</imageobject>
|
|
<textobject>
|
|
<phrase>If <application>nsgmls</application> reports
|
|
success, it merely reports the version of
|
|
<application>nsgmls</application></phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</figure>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="tools-vim">
|
|
<title>VIM</title>
|
|
<indexterm><primary>vim</primary></indexterm>
|
|
<indexterm>
|
|
<primary>Editors</primary>
|
|
<secondary>vim</secondary>
|
|
</indexterm>
|
|
<para>
|
|
<ulink url="http://www.vim.org">http://www.vim.org</ulink>
|
|
</para>
|
|
<para>
|
|
No mention of text editors is complete
|
|
without talking about <application>vi</application>.
|
|
The <application>VIM</application> (Vi IMproved)
|
|
editor has the functionality of
|
|
regular vi and includes <quote>syntax
|
|
highlighting</quote> of tags.</para>
|
|
|
|
<section id="usingvim">
|
|
<title>Getting Started</title>
|
|
<para>
|
|
There are many versions of <application>vi</application>.
|
|
New authors will likely want one of the more
|
|
feature-packed versions for syntax highlighting and
|
|
a graphical interface including mouse control.
|
|
</para>
|
|
<para>
|
|
Red Hat users will want the following packages:
|
|
vim-common, vim-minimal and vim-enhanced.
|
|
Debian users will want the following package: vim.
|
|
For an X interface (including <acronym>GUI</acronym> menus and
|
|
mouse control) users will want
|
|
<application>gvim</application>. The <quote>g</quote> in gvim is for
|
|
<quote>Graphical</quote>.
|
|
</para>
|
|
<para><application>VIM</application> compiles very easy should you need to build your own. Both <command>vim</command> and <command>gvim</command> are built by default. Syntax highlighting is included but not enabled by default if you have to start from scratch; use the <command>:syntax enable</command> command in <application>VIM</application> to turn this feature on.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="vim-new-file">
|
|
<title>Creating New DocBook XML Files</title>
|
|
<para>
|
|
In both <application>vim</application> and
|
|
<application>gvim</application>, <filename
|
|
class="extension">.xml</filename> files will be
|
|
recognized and enter into <quote>SGML mode</quote>.
|
|
A series of known DocBook tags and attributes have
|
|
been entered into <application>vim</application>
|
|
and will be highlighted one color if the name is known
|
|
and another if it is not (for this author the colors are yellow and blue).
|
|
</para>
|
|
<para>
|
|
Having the
|
|
correct document type declaration at the top of your
|
|
document should add the syntax highlighting.
|
|
If you do not see this highlighting you will need to
|
|
force VIM into SGML mode (even for XML files) using the
|
|
command <command>:set ft=sgml</command>. If you are
|
|
working with multiple files for a single XML document you
|
|
can add your document type in <-- comments --> to
|
|
the top of the file to get the correct syntax
|
|
highlighting (you will need to restart the program to see
|
|
the change in highlighting). The top line of this file
|
|
(<filename>tools-text-editors.xml</filename>) looks like this:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
<!-- <!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'> -->
|
|
]]>
|
|
</screen>
|
|
|
|
</section> <!-- vim-new-file -->
|
|
|
|
<section id="vim-spellcheck">
|
|
<title>Spell Check</title>
|
|
<para>
|
|
As in <application>Emacs</application>,
|
|
<application>Vim</application>, will work quite happily with
|
|
<application>aspell</application>. It can be run from within Vim
|
|
with the following:
|
|
<userinput>:! aspell -c %</userinput>.
|
|
</para>
|
|
|
|
<para>
|
|
For more sophisticated spell check alternatives, give <ulink
|
|
url="http://cream.sourceforge.net/">Cream</ulink> or <ulink
|
|
url="http://www.vim.org/scripts/script_search_results.php?keywords=vimspell&script_type=&order_by=rating&direction=descending&search=search">vimspell</ulink> a try.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="vim-tagcompletion">
|
|
<title>Tag Completion</title>
|
|
|
|
<para>
|
|
The following information is provided by <ulink
|
|
url="http://www.digitalhermit.com">Kwan Lowe</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
Vim has a DocBook helper script which can be easily copied into
|
|
your <filename class="directory">.vimscripts</filename>
|
|
directory and used to <quote>auto complete</quote> tags while
|
|
writing DocBook documents. The script can be downloaded from:
|
|
<ulink url="http://www.vim.org/scripts/script.php?script_id=38"
|
|
/>.
|
|
</para>
|
|
|
|
<blockquote>
|
|
<para>
|
|
Grab the file, then untar it. Copy the
|
|
<filename>dbhelper.vim</filename> to your <filename
|
|
class="directory">.vimscripts</filename> directory if you have one.
|
|
</para>
|
|
<screen>
|
|
<prompt>$ </prompt><command>mkdir</command> <filename class="directory">.vimscripts</filename>
|
|
<prompt>$ </prompt><command>cp</command> <filename>dbhelper.vim</filename> <filename class="directory">.vimscripts</filename>
|
|
</screen>
|
|
|
|
<para>
|
|
You'll also have to convert the <filename>dbhelper.vim</filename> file to unix formatting:
|
|
</para>
|
|
|
|
<screen>
|
|
<prompt>$ </prompt><command>dos2unix</command> <filename>dbhelper.vim</filename>
|
|
</screen>
|
|
|
|
<para>
|
|
Next, edit your <filename>.vimrc</filename> file and add the line:
|
|
<userinput>source
|
|
/home/yourname/.vimscripts/dbhelper.vim</userinput>
|
|
</para>
|
|
|
|
<para>
|
|
To use the scripts, enter vi and go into insert mode. Press
|
|
<keycap>,</keycap> (comma) followed by the shortcut. For example:
|
|
<userinput>,dtbk</userinput>
|
|
</para>
|
|
</blockquote>
|
|
|
|
</section>
|
|
|
|
</section> <!-- vim -->
|
|
|
|
<section id="tools-xxe">
|
|
<title>XMLmind XML Editor (XXE)</title>
|
|
|
|
<para>
|
|
<ulink url="http://www.xmlmind.com/xmleditor">
|
|
http://www.xmlmind.com/xmleditor
|
|
</ulink>
|
|
</para>
|
|
|
|
<para>
|
|
David Horton offers the following information:
|
|
</para>
|
|
|
|
<blockquote><para>
|
|
I am a big fan of XMLMind's <application>XXE</application> editor and <application>XFC</application> FO converter.
|
|
It is <quote>free as in beer,</quote> but not necessarily
|
|
<quote>free as in speech.</quote> Very liberal license for personal use
|
|
however. It's Java-based so it works on all sorts of OS's.
|
|
</para></blockquote>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<!-- </section> -->
|