freemarker-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ddek...@apache.org
Subject [1/5] incubator-freemarker git commit: Made place for the Chinese manual.
Date Sun, 20 Dec 2015 13:06:07 GMT
Repository: incubator-freemarker
Updated Branches:
  refs/heads/2.3-gae 41b6f8342 -> 731be2c28


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&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"

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


Mime
View raw message