With the migration to XHTML and CSS, older WYSIWYG editors like Homepage Publisher cannot be used to edit articles for the VOICE Newsletter any more. Authors who don't want to use a text editor have to look for an alternative that supports at least HTML 4 and CSS. NVU is such an alternative and offers easy editing by applying styles like one would assign formatting templates in a word processor. This article goes through the steps of preparing an article according to the author guidelines of the VOICE Newsletter.
Please note that while much is dealt with in great detail, it would be beyond the scope of this article to introduce each and every new style. A description of all available styles and their usage is available in our author guidelines.
Before we can start, we have to set up a working environment.
First of all, download the following:
Required:
Optional but recommended:
NsmConText extension, provides additional editing tools.
Optional:
To install NVU, extract the corresponding ZIP archive into your application directory. This creates an nvu subdirectory. Open the nvu directory and create a WPS object for nvu.exe.
Create a directory where you want to store your article and extract the author package to it.
If you want to install any dictionaries, extensions, or language packs, start NVU and select File > Open file. Change to the directory where you downloaded the files. Select the desired package and follow the instructions.
Alternatively, you can open the extensions manager by selecting Tools > Extensions. Then drag the package you want to install and drop it on the extension manager.
Repeat the above for all packages you want to install.
If you installed a language pack, you need to tell NVU which language you want it to use. Open the properties notebook of the NVU object and type the following into the Parameter entry-field:
-contentLocale <locale> -UILocale <locale>
The parameter locale is a five character language code like the one specified in the LANG environment variable in CONFIG.SYS, with a hyphen as separator instead of an underscore. So, to use an installed German language pack, you would specify:
-contentLocale de-DE -UILocale de-DE
To install HTML Tidy, extract the archive to a temporary directory and move the executables to a directory in your PATH. Note that different versions of HTML Tidy may require different emx DLLs. Consult the README file for details. HTML Tidy offers many configuration options. As a start, create a plain text file called .tidyrc in your HOME directory with the content shown in figure 1 below. If you don't have a HOME directory yet, create a directory where applications can store their settings, e.g., x:\home. Add a corresponding statement to CONFIG.SYS:
SET HOME=x:\home
// HTML Tidy configuration file break-before-br: no drop-proprietary-attributes: yes drop-empty-paras: yes enclose-block-text: yes enclose-text: yes logical-emphasis: yes indent: auto literal-attributes: yes numeric-entities: no quote-marks: yes tidy-mark: no wrap: 120
Now, we need to set a few options. Start NVU, select Tools > Preferences. On the
General tab, make sure that the option Use CSS instead of
HTML elements and attributes is checked. Then, go to the New Page Settings
page. Enter your name into the Author entry field. Make sure that the Character set entry field in the group Internationalization
states ISO-8859-1. In the Markup group of the
Advanced page, choose the XHTML 1 language and
Strict DTD. Also make sure that Return in a paragraph always
creates a new paragraph is checked. If you want to have the spell checker detect errors in the background, you
may want to enable Underline misspelled words.
Confirm the changes by pressing OK.
If you installed the NsmContext extension, open its setup dialog by selecting Tools >
NsmContext.... On the Options page, you can define several external helper
applications for editing HTML, CSS, images, and media. A button to display the currently edited file in an external
browser can be added by selecting Add browser preview in the Context menus group. (This browser has to be defined on the Launchy page.)
The most helpful features of NsmContext, however, are its modifications to the status line. With all options in the
Struct toolbar group enabled, NVU will provide more detailed information about the file
structure. But more to that later.
NsmContext can also integrate HTML Tidy. On the Tidy page, enter the fully qualified
path of the tidy.exe file into the Path to EXE entry
field, or use the button to the right to use a file open dialog. In the entry field Arguments, replace any existing entries with -config %HOME%\.tidyrc -latin1 where
%HOME% picks up the fully qualified path of your HOME directory from the SET HOME=
statement in CONFIG.SYS.
Confirm the changes by pressing OK.
Most of NVU's user interface elements offer tool-tips, i.e., if you position the mouse cursor over a button and wait a bit, a short help text will appear (see figure 2). In addition, most parts of the program window have their own pop-up menu.
NVU comes with a neat tool called the site manager. To display it in the side bar, press [F9]. The site manager allows the user to quickly access as well as manipulate files and folders of a web site that is stored locally on your harddrive or on a remote FTP server. The NsmContext extension also adds some functionality via a pop-up menu.
Right now, your site manager window will be empty. Press Edit sites to open the
Publish Settings dialog. To add the directory where you extracted the author package
as a site, do the following: Enter something like VOICE local into the Site Name entry field. For locally stored sites, it doesn't really matter what you enter as
HTTP address of your homepage, any valid URL should do. Next, we need to specify a
Publishing address. Press Select directory and use
the dialog to select the directory where you extracted the author package. Finally, press the New Site button on the left and the new site should appear in the list above.
Close the dialog by pressing OK.
The previously empty part of the site manager should now display a plus symbol with the site name you entered before to the right. If you click on the plus sign, the author package's directory structure should become visible as you can see in figure 3. You can now use the View combo box to restrict the display to certain types of files, and the icons below it to manipulate files and folders.
In the site manager, files can be opened with a double-click. Try it, and double-click on the file tutorial.html. The file is loaded and displayed to the right.
You may have noticed that there is a tab and a close button similar to those of Firefox at the top of the file display window. Before loading the file, the tab said (Untitled). That should have changed to Writing articles with NVU. Like Firefox, NVU is capable of working with several open files at once. The user can switch between them by clicking on the corresponding tabs. A pop-up menu is available for tab manipulation.
At the moment, the file display window shows the tutorial very much like it would look in a browser. Did you notice the yellow icon at the top left? NVU offers different modes for displaying and editing a file, and they can be selected by clicking on the tabs below the file display window as shown in figure 4. The Normal mode is a nearly WYSIWYG-like mode. The only difference to a browser display is that it also shows icons for invisible parts of the file. In HTML Tags mode, this is done for all HTML tags. This particular mode helps to get a quick overview of the file's structure without clutter due to attributes and the like. In contrast to that, the Source mode displays the full HTML source code with syntax-highlighting, i.e., the code is displayed with different colors to improve readability. If you need to check if NVU has made some mistake and generated code you don't want, this is the place to find it. This mode also provides more control. More experienced users will find that some things can be done faster here than via the related dialogs. Finally, the Preview mode can be used to view the file as — an earlier version of — Mozilla would display it.
Try to switch back and forth between the different modes to see how the elements in the display are related.
NVU has two toolbars, that provide shortcuts for menu items of the pull-down menu. The composition toolbar, which is located directly below the pull-down menu, contains some items from the Insert menu, while the format toolbar (see figure 5) contains items from the Format menu.
The tool bar buttons not only allow the application of tags and styles but also reflect the current status at the cursor position as commonly done in word processors. Try it and position the cursor somewhere in the text and you will see the tool bars update accordingly.
At the very bottom of the NVU window, you can see the status bar. This is one of the most important tools for handling styles in NVU. It always displays the nesting of HTML elements for the current cursor position starting with the <body> tag. Generally, the styles of one element are inherited by all elements contained therein, so the element "path" that the status bar displays helps to understand which styles actually apply. If you have installed the NsmContext extension, the status bar also displays any CSS classes or IDs that are applied to a an element, and tool tips can provide even more information.
Try it and position the cursor in headers, emphasized text, and boxes and you will see how the status bar updates
accordingly. If you position the cursor in the XHTML
acronym in the introductory paragraph of this
article, you will see <body> <p> <acronym> in the standard status
bar, and <body> <p class="bSummary"> <acronym> in the
NsmContext-enabled status bar as shown in figure 6. If you position the mouse pointer over <acronym>, you can even see the title attribute's content displayed in a tool tip.
The status bar is not only a means of information but also a tool for selecting elements and applying styles. If you move the mouse pointer over a tag in the status bar, it changes to a push button. Pressing the button selects the whole element. In addition, you can invoke a pop-up menu by pressing the right mouse button, which lets you edit the element and change styles and IDs.
We will now go through the actual process of preparing this very article for submission. You can always look at this file to see the desired result.
First of all, we need to load the raw article file. Double-click on tutorial_raw.html in the site manager. If you switch to Source mode, you can see that this file just contains the raw text paragraphs.
Let's switch back to Normal mode and take a look at the text. The first two paragraphs apparently contain the article title, subtitle and information about the author. The third paragraph provides an introduction to the article, the rest looks like a howto. Different types of lists have been used, even nested ones judging from the changes in numbering. There is also text that looks like file names, object names, GUI elements, code and commands.
Before we start editing, we save the file under a different name so we can get back to the original in case of problems. Choose File > Save as..., type tutorial_1.html into the File name entry-field and press OK.
Judging from the content of the next paragraph, the reader may not be able to continue with the installation if he does not follow the advice. To emphasize this important information, we change the tag and apply a special style. Mark the paragraph by placing the cursor inside it and pressing the paragraph tag button in the status line. Then select Generic container (div) from the format list and bCaution from the styles list.
Next up, we have a file listing with a caption at the top. Mark the paragraph with the caption taking the above note regarding generic containers into account. Select Generic container (div) from the format list and bHeader from the styles list. File content should always be displayed as entered so one can easily copy it to an article. Mark it and select Preformat from the format list and bFileContent from the styles list.
The following section introduces several new terms, e.g., the modes Normal, HTML Tags, Source, and Preview. Mark these via the emphasize button. Furthermore, we should emphasize the fact that files can not only be viewed but also edited in each of the modes, and the location of these "tabs" as well. Select "and edited" and "below" and press the emphasize button for both. To clarify the difference between the modes, we should add a strong emphasis to "all" by selecting the text and pressing the strong emphasize button.
Looking at the above, we decide that we want to show a screenshot of the mode tabs. Mark the second paragraph of the section and use the same method as described above. Insert the nvu_mode_tabs.png image and enter Display and editing mode tabs as alternate text. Because the image could cause confusion where the text belongs, we let it occupy its own line and apply the bImageCenter style to the container.
The section "The article itself" describes the steps that are required to format the article. As there is a certain sequence, an ordered or numbered list should be used. Mark all the list items and press the numbered list button. Remove the leading numbers and spaces afterwards.
There are two ways to correct this:
The ordered list items contain several reminder boxes. (See the paragraphs starting with "The generic container," "Do not use the standard," and "NVU converts each marked.") These have to be adjusted using the same method as described for the paragraphs above. Mark them, choose Generic container (div) from the format list, and select bPin from the styles list.
You will also see a nested bulleted list. The above process will have converted its items to normal items of the ordered list. To correct this, mark the list items of the bulleted list and press the indent text button. This takes them "one level deeper." To change the list type, select both list items and press the bulleted list button. If the indentation didn't really change in the process, NVU needs to readjust the list nesting structure. Select Tools > Markup cleaner. Make sure that Fix nested lists is enabled and press Clean up.
We need to provide some information for the VOICE editors to be able to build the article. This is done using
separate files that define a number of variables. Open tutorial_raw.def in a text
editor like E or EPM. This file will later be automatically be processed by PPWizard to generate the article header
and so on. Every line that contains a #define
statement sets a value for a variable (see figure 7).
#define article_title #define article_subtitle #define author #define author_mail ;#define translator ;#define translator_mail ;define author2 ;define author2_mail ;#define translator ;#define translator_mail ;#define formatter ;#define formatter_mail ;#define proofreader ;#define proofreader_mail #define description #define keywords #define productname #define developer #define productprice #define links \ : <a href=""></a><br /> %\ : <a href=""></a> #define author_about <p></p> #define use_author_box true #define use_reftable true #define summary \
#define article_title
. Now insert the clipboard
content.#define
article_subtitle
.#define author
.#define
author_mail
.#define description
. The text provided
here can be used by search engines when displaying results.#define keywords
. While many search engines tend to
ignore this info nowadays, it's still useful.If a VOICE Newsletter article provides any links, we list them in a references box below the article itself.
Please add the links below the #define links \
line and use the following lines as a template, with
the second line being the last one for links. I.e., insert the link description before the colon, and the URL
between the quotes and again between the opening and closing tag for the link. For the NVU link in the
"Required software" section, this would look like the following:
NVU: <a href="http://weilbacher.org/Mozilla/builds.html">http://weilbacher.org/Mozilla/builds.html</a><br /> %\
It's always nice to know a bit about an author's background. This kind of information is provided with the author_about variable. Copy the following to the corresponding line:
Christian Hennecke is the Editor in Chief of the VOICE Newsletter and co-owner of a small IT consulting company.
As noted above, NVU is not perfect. While the markup cleaner tool helps to remove superfluous code and correct a few errors, other things may have gone wrong. Also, NVU doesn't exactly produce pretty-printed code. To minimize problems, you can run HTML Tidy against your article. Use the following syntax:
tidy.exe -config config_file -latin1 input_file > output_file
Details on other options are available by issueing tidy -help.
For this file, the corresponding command and output could look like this:
[C:\]tidy -config %HOME%\.tidyrc -latin1 tutorial_finished.html > tutorial_finished_tidied.html
line 1067 column 1 - Warning: <table> lacks "summary" attribute Info: Doctype given is "-//W3C//DTD XHTML 1.0 Strict//EN" Info: Document content looks like XHTML 1.0 Transitional 1 warning, 0 errors were found! The table summary attribute should be used to describe the table structure. It is very helpful for people using non-visual browsers. The scope and headers attributes for table cells are useful for specifying which headers apply to each table cell, enabling non-visual browsers to provide a meaningful context for each cell. For further advice on how to make your pages accessible see http://www.w3.org/WAI/GL. You may also want to try "http://www.cast.org/bobby/" which is a free Web-based service for checking URLs for accessibility. To learn more about HTML Tidy see http://tidy.sourceforge.net Please send bug reports to html-tidy@w3.org HTML and CSS specifications are available from http://www.w3.org/ Lobby your company to join W3C, see http://www.w3.org/Consortium
Apparently, we forgot to supply a summary attribute for the table. Since this table is pretty lean and also has a meaningful caption, we can skip this. The problem with the content type is rather marginal and you can leave it to the editors.
Now you could zip up the tidied XHTML file and the images and send them to the editors.
The following provides an overview and reminder of some shortcomings and peculiarities of NVU.
NVU lacks support for some tags. To be able to reach the desired effect anyway, VOICE provides alternatives styles that are later converted to the correct tags by us. See table 1 for an overview of these tags. While the iQuote and iKeyboard styles can be used like any other inline style, i.e., by marking the text and selecting the style from the styles list, the bBlockquote style should be applied to a paragraph or be used with a generic container that includes several paragraphs.
Tag | Class | Description |
---|---|---|
<blockquote> | bBlockquote | A block quote that creates its own paragraph(s). |
<q> | iQuote | A quote inside a paragraph. |
<kbd> | iKeyboard | Things to be entered by the user using the keyboard. Mostly key combinations. |
Applying inline styles, i.e., those starting with a lower-case "i", to the whole content of block-level elements like paragraphs or list items can yield unwanted results because NVU may actually apply the style to the block-level element itself. To avoid this, insert a space at the very beginning. Then mark the text except for the space character and apply the style. Afterwards, delete the surplus space character.
Inserting block-level elements like paragraphs, generic containers, or preformatted text into other block-level elements, or changing existing text accordingly can be difficult and easily lead to unwanted results. The best way is to first separate the elements with line breaks using [Shift-Enter]. Then each part can be changed by marking it and selecting the appropriate item from the format list.
When converting text to a list, each block-level element is converted to a list item, even those that should be part of another list item. As a remedy, use the method described in the previous paragraph.
Changing any existing text to preformatted text is likely to cause every line to be converted separately or to cause unwanted extra line breaks. To convert a block of text as a whole, cut it to the clipboard, create a new paragraph, and change that paragraph to preformatted text. Then place the cursor inside and select Edit > Paste without formatting.