# XML - Managing Data Exchange/Author guidelines

## Editing Chapters

You simply click on the \"edit this page\" tab at the top of any page
you want to edit. You can also just edit a section or subsection - any
place you see a little \'edit\' to the far right above a line, click on
it to edit that section. The thoughts behind the editing process of the
chapters will be documented in the \"discussion\" tab of each chapter -
go there to record your intentions for your assigned chapter.

If you would like to make any suggestions to the editorial board, we
welcome them. At the top of the XML: Managing Data Exchange contents
page is a tab to \"discussion\" follow that link and edit the page with
your comments, be sure to follow the directions for entries.

-   **Use wiki code, not HTML code** when you edit a page.

```{=html}
<!-- -->
```
-   how to make a link : \[\[XML: Managing Data
    Exchange/NameOfThePage(on the page)\|NameOfThePage(displayed as the
    link)\]\]

```{=html}
<!-- -->
```
-   no plagiarism : please use citations and references to books,
    articles, and websites that have helped you contribute to the book.

```{=html}
<!-- -->
```
-   All figures and graphics should be prefixed with \'xml\' to avoid
    accidentally overwriting another file (e.g., xmldmcity defines the
    data model for city).

```{=html}
<!-- -->
```
-   Where possible use Portable Network Graphics
    (PNG) for graphics because of its
    superiority to GIF and JPEG. Also, PNG is Open Source.
    OpenOffice.org Draw can be used to
    create PNG files.

## Consistency guidelines

**- developed to create a consistent look and feel to the book**

### Layout

-   **Chapter summary required**

The bottom of each chapter should include a chapter summary highlighting
the key points of the chapter. Follow the formatting guideline detailed
later on this page.

-   **Bold new words**

As new concepts and terminology are introduced in each chapter, make
sure that they are defined first before using them; so that the reader
understands what the words and ideas represent. **Bold** the first
occurrence of the word (or preceding the definition).

-   **Use the sentence format for titles**

Capitalize the first letter of a title and allow the rest of the letters
to be lower case, as in this title.

-   **Avoid the use of underline and all capital words**

```{=html}
<!-- -->
```
-   **Tables, figures, and code references**

For consistency, label all tables, figures (e.g. charts and photos), and
code examples as \"exhibits.\" Place the label for exhibits at the top
of the exhibit, flush left, and enumerate the exhibits, followed by a
brief caption. Examples: \"Exhibit 1: XML data types\" and \"Exhibit 2:
Schema code example\"

-   **Concept capsules and breathing room**

Think of your chapter as a data model or a large steak. A useful data
model is broken down into its smallest attributes that require recording
and maintaining for future analysis. A large steak is best eaten in bite
size pieces to prevent choking and promote good digestion. As you revise
your chapter consider the basic elements of your topic; break your topic
down and present each element in a section - so that it is easy for the
reader to follow and understand each part. Feel free to use bullets to
represent lists.

To continue with the steak analogy, it is also good to eat slowly,
taking breaths between each bite. Allow for spaces between each
subsection and greater spaces between each section. This opens up the
text so that it does not appear to dense and compact - and therefore
intimidating.

-   **NetBeans (or other XML editor) Examples**

Scroll down the contents page to \"Appendices\". You will see a link to
the chapter \"Using an XML editor\". When you open this link - go to the
edit this page tab and insert a link under the NetBeans heading with the
name of your chapter. This is the format for the link: \[\[XML: Managing
Data Exchange/ChapterName(NetBeans)\|ChapterName\]\] After you save your
edit, the XML Editor page will contain a link to your new NetBeans page.
It will appear red because no information has been posted to that page
yet. Click on the link and paste all the NetBeans information from your
chapter into the edit box. In your assigned chapter, at the places where
there were NetBeans information (that you just cut and paste into the
XML editor page) - put a link to the XML editor - your Chapter page.

-   **Help:Wikibooks** \<= this link will
    provide several wiki guidelines - this page is also accessible from
    the \'help\' link in the navigation box on the left bar of every one
    of these Wikibook pages. It contains information on inserting
    pictures, creating tables using wiki language (which is much easier
    to write and read).

This help page also has a link to a \"sandbox.\" This is a blank page
that allows you to experiment with wiki without affecting a real page.

### Code examples

-   Make all code examples a uniform color (black)---some are all black;
    some are multicolored. Please change the ones that are multicolored
    to all black.

```{=html}
<!-- -->
```
-   HTML code is lower case.

```{=html}
<!-- -->
```
-   Keep the comments in the code, but put a space above and bellow each
    comment.

```{=html}
<!-- -->
```
-   Include the file name of the code in a comments tag. If you are the
    author of the code, include your name and the date you authored the
    code in the comments. See example:

```{=html}
<!-- -->
```
    <nowiki>
        <!--
             Document   : city.xsd
             Created on : March 1, 2005
             Author     : Tim Jones
        -->
    </nowiki>

-   Keep all the example codes in the chapter on the same topic---the
    TOURGUIDE. If there are examples in your chapter that deviate from
    this theme, please change them to show examples from TOURGUIDE.

```{=html}
<!-- -->
```
-   If your code contains HTML or the XML declaration then you will want
    to put the tags \<pre\> \... \</pre\>

```{=html}
<!-- -->
```
-   In order to get those \'pre\' tags to show up I had to use the tags
    \<nowiki\> \... `</nowiki>`{=html}

If you run into trouble while inserting code, one of the two tags
mentioned above might be able to get you out.

-   You do **not** have to create a table around samples of a code
    example; usually just putting a few spaces in front of each line
    will create the dashed blue lined box

### Spelling

-   Use the spelling \"stylesheet\" instead of \"style sheet.\"

```{=html}
<!-- -->
```
-   Use the spelling \"opening tag\" instead of \"opening-tag.\"

```{=html}
<!-- -->
```
-   **Check your wiki text with a spellchecker** (e.g. copy and paste in
    a text editor that supports spell checking).

### Exercises & Answers

Create two links at the bottom of your chapter, one to an Exercises page
and one to the Answers page already made (you can find this answer page
link at the bottom of the contents page).

In the Exercises page, cut and paste your chapter exercises into a **new
page**. An easy way to create a new page is simply to go to your main
chapter page, type \"exercises\" at the end of the URL, and hit enter.
If the page does not exist, Wikipedia will ask you to create the page by
going to \"edit this page.\"

At the top and bottom of the Exercises page, provide a link to the
chapter and the Answers page---and vice versa with the Answers page.

### Elements of Style - Principles of Composition

**taken from *the Elements of Style* - by William Strunk and E.B.
White**

-   **Make the paragraph the unit of composition** - The subject will
    need to be broken down into topics, and topics will need to be
    broken down into concepts and subconcepts. Each concept should be
    explored within its own paragraph.

```{=html}
<!-- -->
```
-   **Put statements in positive form** - \"Make definitive assertions.
    Avoid tame, hesitating, noncommittal language. Use the word \'not\'
    as a means of denial or in antithesis, never as means of evasion.\"

```{=html}
<!-- -->
```
-   **Use definite, specific, concrete language** - \"Prefer the
    specific to the general, the definite to the vague, the concrete to
    the abstract.\"

```{=html}
<!-- -->
```
-   **Omit needless words** - \"A sentence should contain no unnecessary
    words, a paragraph no unnecessary sentences\...Many expressions
    violate this principle: \'the fact that,\' he is a man who \... - he
    \...\"

```{=html}
<!-- -->
```
-   **Avoid a succession of loose sentences**

```{=html}
<!-- -->
```
-   **Express coordinate ideas in similar form**

```{=html}
<!-- -->
```
-   **Keep related words together**

```{=html}
<!-- -->
```
-   **Place the emphatic words of a sentence at the end**

## Source code

For inserting source code (e.g., XML or Java) into the book, use the
following format:

    <nowiki>
      <country>
          <code>au</code>
          <country>Australia</country>
          <flag>au.gif</flag>
      </country>
    </nowiki>

Use the following wiki code:


    &lt;pre&gt;&lt;nowiki&gt;
      <country>
          <code>au</code>
          <country>Australia</country>
          <flag>au.gif</flag>
      </country>
    &lt;/nowiki&gt;&lt;/pre&gt;

## Section summary

Section summaries should appear in the following format:

  -------------------
  A chapter summary
  -------------------

Use the following wiki code:

    {| style="background:linen; border: 1px solid black; padding: 1em; width: 100%;"
    |- 
    | A chapter summary
    |-
    |}

## Story

Stories/case studies should appear in the following format:

  ---------
  A story
  ---------

Use the following wiki code:

    {| style="background: lightyellow; border: 1px solid black; padding: 1em; width: 100%;"
    |- 
    | A story
    |-
    |}

## References

-   A guide to Wiki
    editing
    is online
-   HTML tables can be converted to Wiki format using an online
    tool.

