/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
 
Guide to FreeMarker Manual for Editors
======================================

Non-technical
-------------

- The Template Author's Guide is for Web designers. Assume that a
  designer is not a programmer, (s)he doesn't even know what is Java.
  Forget that FM is implemented in Java when you edit the Template
  Author's Guide. Try to avoid technical writing.

- In the Guide chapters, be careful not to mention things that were
  not explained earlier. The Guide chapters should be understandable
  if you read them continuously.

- If you add a new topic or term, don't forget to add it to the Index.
  Also, consider adding entries for it to the Glossary.

- Don't use too sophisticated English. Use basic words and grammar.


Technical
---------

- For the editing use XXE (XMLmind XML Editor), with its default XML
  *source* formatting settings (identation, max line length and like).
  You should install the "DocBook 5 for Freemarker" addon, which you can
  find inside the "docgen" top-level SVN module.

- The HTML is generated with Docgen (docgen.jar), which will check some
  of the rules described here. To invoke it, issue "ant manual" from
  the root of the "freemarker" module. (Note: you may need to check out
  and build "docgen" first.)

- Understand all document conventions in the Preface chapter. Note that
  all "programlisting"-s should have a "role" attribute with a value that
  is either: "template", "dataModel", "output", "metaTemplate" or
  "unspecified". (If you miss this, the XXE addon will show the
  "programlisting" in red.)

- Verbatim content in flow text:

  * In flow text, all data object names, class names, FTL fragments,
    HTML fragments, and all other verbatim content is inside "literal"
    element.

  * Use replaceable element inside literal element for replaceable
    parts and meta-variables like:
    <literal&lt;if <replaceable>condition</replaceable>></literal>
    <literal><replaceable>templateDir</replaceable>/copyright.ftl</literal>

- Hierarchy:

  * The hierarchy should look like:

      book -> part -> chapter -> section -> section -> section -> section

    where the "part" and the "section"-s are optional.
    Instead of chapter you may have "preface" or "appendix".

  * Don't use "sect1", "sect2", etc. Instead nest "section"-s into each other,
    but not deeper than 3 levels.

  * Use "simplesect" if you want to divide up something visually, but
    you don't want those sections to appear in the ToC, or go into their own
    HTML page. "simplesect"-s can appear under all "section" nesting
    levels, and they always look the same regardless of the "section"
    nesting levels.

- Lists:

  * When you have list where the list items are short (a few words),
    you should give spacing="compact" to the "itemizedlist" or
    "orderedlist" element.

  * Don't putting listings inside "para"-s. Put them between "para"-s instead.

- Xrefs, id-s, links:

  * id-s of parts, chapters, sections and similar elements must
    contain US-ASCII lower case letters, US-ASCII numbers, and
    underscore only. id-s of parts and chapters are used as the
    filenames of HTML-s generated for that block.
    When you find out the id, deduce it from the position in the ToC
    hierarchy. The underscore is used as the separator between the path
    steps.

  * All other id-s must use prefix:
    - example: E.g.: id="example.foreach"
    - ref: Reference information...
      * directive: about a directive. E.g.: "ref.directive.foreach"
      * builtin
    - gloss: Term in the Glossary
    - topic: The recommended point of document in a certain topic
      * designer: for designers.
          E.g.: id="topic.designer.methodDataObject"
      * programmer: for programmers
      * or omit the secondary category if it is for everybody
    - misc: Anything doesn't fit in the above categories

  * When you refer to a part, chapter or section, often you should use
    xref, not link. The xreflabel attribute of the link-end should not be set;
    then it's deduced from the titles.

- The "book" element must have this attribute: conformance="docgen"

- It sometimes happens that you want to change some content that you see in
  the generated output, which you can't find in the DocBook XML. In such case,
  check the contents docgen.cjson, which should be in the same directory as
  the XML. If it's not there either, it's perhaps hard-wired into the
  templates in docgen.
