Repository: incubator-freemarker Updated Branches: refs/heads/2.3 ad73f5f4a -> f0695c39a
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/en_US/docgen-help/editors-readme.txt ---------------------------------------------------------------------- diff --git a/src/manual/en_US/docgen-help/editors-readme.txt b/src/manual/en_US/docgen-help/editors-readme.txt new file mode 100644 index 0000000..5280d97 --- /dev/null +++ b/src/manual/en_US/docgen-help/editors-readme.txt @@ -0,0 +1,105 @@ +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<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" http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/en_US/docgen-misc/googleAnalytics.html ---------------------------------------------------------------------- diff --git a/src/manual/en_US/docgen-misc/googleAnalytics.html b/src/manual/en_US/docgen-misc/googleAnalytics.html new file mode 100644 index 0000000..bf440f2 --- /dev/null +++ b/src/manual/en_US/docgen-misc/googleAnalytics.html @@ -0,0 +1,9 @@ +<script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-55420501-1', 'auto'); + ga('send', 'pageview'); +</script> http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/en_US/docgen-originals/figures/model2sketch_with_alpha.png ---------------------------------------------------------------------- diff --git a/src/manual/en_US/docgen-originals/figures/model2sketch_with_alpha.png b/src/manual/en_US/docgen-originals/figures/model2sketch_with_alpha.png new file mode 100644 index 0000000..ce120cc Binary files /dev/null and b/src/manual/en_US/docgen-originals/figures/model2sketch_with_alpha.png differ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/en_US/docgen-originals/figures/odg-convert-howto.txt ---------------------------------------------------------------------- diff --git a/src/manual/en_US/docgen-originals/figures/odg-convert-howto.txt b/src/manual/en_US/docgen-originals/figures/odg-convert-howto.txt new file mode 100644 index 0000000..1db294c --- /dev/null +++ b/src/manual/en_US/docgen-originals/figures/odg-convert-howto.txt @@ -0,0 +1,24 @@ +Converting to SVG: +1. Open the ODG file with Libeoffice/OpenOffice Draw +2. Ctrl+A to select all objects +3. File/Export..., chose SVG format, and then tick "Selection" +4. Check the result. If contour lines at the right and bottom edge of the + figure are partically clipped (stroke width is halved), set a stroke with + other than 0 for all shapes. + +Converting to a decent quality (though non-transparent) PNG: +1. Open the ODG file with Libeoffice/OpenOffice Draw +2. Export to PDF +3. Open PDF in Adobe Acrobat Reader +4. Go to Adobe Acrobat Reader preferences and set it to not use subpixel + anti-aliasing, just normal anti-aliasing. They used to call this LCD vs + Monitor mode. +5. Zoom in/out until you get the desired size in pixels, take a + screen shot, crop it in some image editor, save it as PNG. + +Converting to transparent but somewhat ugly PNG: +1. Convert to SVG as described earlier +2. Use Apache Batik Rasterizer command line utility like: + $BARIK_INSTALLATION\batik-rasterizer-1.8.jar -dpi 72 -m image/png ${FIGURE}.svg + If Batik fails (as it doesn't support all SVG features), use Inkscape. + Of course avoid supixel anti-aliasing, as it's not device independent. http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/en_US/docgen-originals/figures/overview.odg ---------------------------------------------------------------------- diff --git a/src/manual/en_US/docgen-originals/figures/overview.odg b/src/manual/en_US/docgen-originals/figures/overview.odg new file mode 100644 index 0000000..0533b7c Binary files /dev/null and b/src/manual/en_US/docgen-originals/figures/overview.odg differ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/en_US/docgen-originals/figures/tree_with_alpha.png ---------------------------------------------------------------------- diff --git a/src/manual/en_US/docgen-originals/figures/tree_with_alpha.png b/src/manual/en_US/docgen-originals/figures/tree_with_alpha.png new file mode 100644 index 0000000..dc4fba8 Binary files /dev/null and b/src/manual/en_US/docgen-originals/figures/tree_with_alpha.png differ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/en_US/docgen.cjson ---------------------------------------------------------------------- diff --git a/src/manual/en_US/docgen.cjson b/src/manual/en_US/docgen.cjson new file mode 100644 index 0000000..221f349 --- /dev/null +++ b/src/manual/en_US/docgen.cjson @@ -0,0 +1,112 @@ +//charset: UTF-8 + +deployUrl: "http://freemarker.org/docs/"; +onlineTrackerHTML: "docgen-misc/googleAnalytics.html" +searchKey: "014728049242975963158:8awjt03uofm" +validation: { + programlistingsRequireRole + // programlistingsRequireLanguage + maximumProgramlistingWidth: 100 +} +showXXELogo +generateEclipseTOC +// eclipse: { +// link_to: "freemarker-toc.xml#ManualLink" +// } + +removeNodesWhenOnline: [ "preface" ] + +copyrightHolder: "The FreeMarker Project" +copyrightStartYear: 1999 + +seoMeta: { + "dgui_quickstart": { + "title": "Getting Started with template writing" + } + "pgui_quickstart": { + "title": "Getting Started with the Java API" + } +} + +logo: { + href: "http://freemarker.org"; + src: logo.png, + alt: "FreeMarker" +} + +olinks: { + homepage: "http://freemarker.org/"; + api: "api/index.html" + + // Homepage links: + freemarkerdownload: "http://freemarker.org/freemarkerdownload.html"; + contribute: "http://freemarker.org/contribute.html"; + history: "http://freemarker.org/history.html"; + what-is-freemarker: "id:preface" + mailing-lists: "http://freemarker.org/mailing-lists.html"; + + // External URL-s: + onlineTemplateTester: "http://freemarker-online.kenshoo.com/"; + twitter: "https://twitter.com/freemarker"; + sourceforgeProject: "https://sourceforge.net/projects/freemarker/"; + githubProject: "https://github.com/freemarker/freemarker"; + newBugReport: "https://sourceforge.net/p/freemarker/bugs/new/"; + newStackOverflowQuestion: "http://stackoverflow.com/questions/ask?tags=freemarker"; +} + +internalBookmarks: { + "Alpha. index": alphaidx + "Glossary": gloss + "Expressions": exp_cheatsheet + "?builtins": ref_builtins_alphaidx + "#directives": ref_directive_alphaidx + ".spec_vars": ref_specvar + "FAQ": app_faq +} + +tabs: { + "Home": "olink:homepage" + "Manual": "" // Empty => We are here + "Java API": "olink:api" +} + +// Available icons: +// .icon-heart +// .icon-bug +// .icon-download +// .icon-star +secondaryTabs: { + "Contribute": { class: "icon-heart", href: "olink:contribute" } + "Report a Bug": { class: "icon-bug", href: "olink:newBugReport" } + "Download": { class: "icon-download", href: "olink:freemarkerdownload" } +} + +footerSiteMap: { + "Overview": { + "What is FreeMarker?": "olink:what-is-freemarker" + "Download": "olink:freemarkerdownload" + "Version history": "id:app_versions" + "About us": "olink:history" + "License": "id:app_license" + } + "Handy stuff": { + "Try template online": "olink:onlineTemplateTester" + "Expressions cheatsheet": "id:exp_cheatsheet" + "#directives": "id:ref_directive_alphaidx" + "?built_ins": "id:ref_builtins_alphaidx" + ".special_vars": "id:ref_specvar" + } + "Community": { + "FreeMarker on Github": "olink:githubProject" + "Follow us on Twitter": "olink:twitter" + "Report a bug": "olink:newBugReport" + "Ask a question": "olink:newStackOverflowQuestion" + "Mailing lists": "olink:mailing-lists" + } +} + +socialLinks: { + "Github": { class: "github", href: "olink:githubProject" } + "Twitter": { class: "twitter", href: "olink:twitter" } + "Stack Overflow": { class: "stack-overflow", href: "olink:newStackOverflowQuestion" } +} http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/en_US/favicon.png ---------------------------------------------------------------------- diff --git a/src/manual/en_US/favicon.png b/src/manual/en_US/favicon.png new file mode 100644 index 0000000..ce0de20 Binary files /dev/null and b/src/manual/en_US/favicon.png differ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/en_US/figures/model2sketch.png ---------------------------------------------------------------------- diff --git a/src/manual/en_US/figures/model2sketch.png b/src/manual/en_US/figures/model2sketch.png new file mode 100644 index 0000000..93f9a6b Binary files /dev/null and b/src/manual/en_US/figures/model2sketch.png differ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/en_US/figures/overview.png ---------------------------------------------------------------------- diff --git a/src/manual/en_US/figures/overview.png b/src/manual/en_US/figures/overview.png new file mode 100644 index 0000000..b32e0bd Binary files /dev/null and b/src/manual/en_US/figures/overview.png differ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/en_US/figures/tree.png ---------------------------------------------------------------------- diff --git a/src/manual/en_US/figures/tree.png b/src/manual/en_US/figures/tree.png new file mode 100644 index 0000000..dcd9bf3 Binary files /dev/null and b/src/manual/en_US/figures/tree.png differ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/en_US/logo.png ---------------------------------------------------------------------- diff --git a/src/manual/en_US/logo.png b/src/manual/en_US/logo.png new file mode 100644 index 0000000..193dc11 Binary files /dev/null and b/src/manual/en_US/logo.png differ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/favicon.png ---------------------------------------------------------------------- diff --git a/src/manual/favicon.png b/src/manual/favicon.png deleted file mode 100644 index ce0de20..0000000 Binary files a/src/manual/favicon.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/figures/model2sketch.png ---------------------------------------------------------------------- diff --git a/src/manual/figures/model2sketch.png b/src/manual/figures/model2sketch.png deleted file mode 100644 index 93f9a6b..0000000 Binary files a/src/manual/figures/model2sketch.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/figures/overview.png ---------------------------------------------------------------------- diff --git a/src/manual/figures/overview.png b/src/manual/figures/overview.png deleted file mode 100644 index b32e0bd..0000000 Binary files a/src/manual/figures/overview.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/figures/tree.png ---------------------------------------------------------------------- diff --git a/src/manual/figures/tree.png b/src/manual/figures/tree.png deleted file mode 100644 index dcd9bf3..0000000 Binary files a/src/manual/figures/tree.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/logo.png ---------------------------------------------------------------------- diff --git a/src/manual/logo.png b/src/manual/logo.png deleted file mode 100644 index 193dc11..0000000 Binary files a/src/manual/logo.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/731be2c2/src/manual/zh_CN/placeholder.txt ---------------------------------------------------------------------- diff --git a/src/manual/zh_CN/placeholder.txt b/src/manual/zh_CN/placeholder.txt new file mode 100644 index 0000000..a83feff --- /dev/null +++ b/src/manual/zh_CN/placeholder.txt @@ -0,0 +1,5 @@ +Add the Chinese Manual here, then delete this file. +You can use these to test if the Manual is generated succesfully: + + ant manualOffline_zh_CN + ant manualFreemarkerOrg_zh_CN
