mirror of https://github.com/tLDP/LDP
374 lines
13 KiB
XML
374 lines
13 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-nedit">
|
|
<title>nedit</title>
|
|
<indexterm><primary>nedit</primary></indexterm>
|
|
<indexterm>
|
|
<primary>Editors</primary>
|
|
<secondary>nedit</secondary>
|
|
</indexterm>
|
|
<para>
|
|
<ulink url="http://sourceforge.net/projects/nedit/">
|
|
http://sourceforge.net/projects/nedit/</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.
|
|
<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="xmlform">
|
|
<title>XMLForm</title>
|
|
<para><ulink url="http://www.datamech.com/XMLForm/" /></para>
|
|
|
|
<para>This web-based application allows you to put in the URL for XML source, or copy and paste the XML directly into the web form. The application then breaks down your document into a series of form fields that hide the DocBook tags so that you may edit the content directly. Version 5 is available from <ulink url="http://www.datamech.com/XMLForm/formGenerator5.html" />. This application is best on shorter documents (less than 20 pages printed).</para>
|
|
|
|
<para>As this is an on-line tool, it will be good for small updates only.</para>
|
|
</section>
|
|
|
|
<section id="tools-xxe">
|
|
<title>XMLmind XML Editor (XXE)</title>
|
|
|
|
<para>
|
|
<ulink url="http://www.xmlmind.com/xmleditor" />
|
|
</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> -->
|