diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/build.xml | 517 | ||||
| -rw-r--r-- | docs/pom.xml | 89 | ||||
| -rw-r--r-- | docs/readme-docs-module.adoc | 98 | ||||
| -rw-r--r-- | docs/src/main/resources/local.properties | 12 |
4 files changed, 0 insertions, 716 deletions
diff --git a/docs/build.xml b/docs/build.xml deleted file mode 100644 index e0083ec38..000000000 --- a/docs/build.xml +++ /dev/null @@ -1,517 +0,0 @@ -<!-- -*- Mode: SGML; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- --> -<!-- ========================================================================= --> -<!-- Copyright (c) 2002 Palo Alto Research Center, Incorporated (PARC), --> -<!-- 2004-2005 Contributors. --> -<!-- All rights reserved. --> -<!-- This program and the accompanying materials are made available --> -<!-- under the terms of the Eclipse Public License v 2.0 --> -<!-- which accompanies this distribution and is available at --> -<!-- https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt --> -<!-- --> -<!-- Contributors: --> -<!-- Xerox/PARC initial implementation --> -<!-- ========================================================================= --> - -<project name="docs" default="dist" basedir="."> - - <property name="project.name" value="build-docs" /> - - <target name="product" depends="local-dist" /> - <target name="clean" - depends="clean-doc-directories" - /> - - <!-- ===================================================================== --> - <!-- Init --> - <!-- ===================================================================== --> - - <import file="${basedir}/../build/build-properties.xml"/> - - <target name="init" depends="init-properties,init-directories"> - - <property name="docs.src.pattern" - value="**/*.xml,**/*.html,**/*.doc,**/*.gif,**/*.java,**/*.lst,**/*.pdf" - /> - <property name="docs.src.dir" - location="${aspectj.modules.docs.dir}" - /> - - <property name="docs.dist.dir" - location="${aj.dist.dir}/docs" - /> - <property name="docs.temp.dir" - location="${aj.temp.dir}/doc" - /> - <property name="web.doc.dir" - location="${aj.webDeploy.dir}/documentation/dist" - /> - - <property name="docs.product.name" - value="aspectj-docs-${build.version}" - /> - - <property name="docs.product.zip" - location="${aj.dist.dir}/${docs.product.name}.zip" - /> - <!-- must specify (not *.gif) to not delete other gifs during build-in-place --> - <!-- to find refs: gp ax imagedata | sed -n 's|.*\=\"\(..*\)\".*|\1|p' --> - <property name="devguide.icons.dir" - location="${aspectj.modules.dir}/ajde/src/main/resources/org/aspectj/ajde/resources/actions" - /> - <property name="include.devguide.icons" - value="build.png,openConfig.png,browseroptions.png" - /> - - <!-- callers of xml-html use these by default --> - <property name="chunk.xsl.source" - location="${aspectj.modules.lib.dir}/docbook/docbook-xsl/html/chunk.xsl" - /> - <property name="nochunk.xsl.source" - location="${aspectj.modules.lib.dir}/docbook/docbook-xsl/html/docbook.xsl" - /> - <!-- default xml-html nochunking file (0-length dummy created when chunking) --> - <property name="xml-target-file" - location="${docs.temp.dir}/xml-target-file.dummy" - /> - <!-- default value for xml-html copying (copy all graphics) --> - <property name="xml-html-copy" value="*.gif,*.png" /> - <property name="xml-html-stylesheet" value="aspectj-docs.css" /> - <property name="binary.pattern" - value="**/*.gif,**/*.png,**/*.doc,**/*.pdf,**/*.jpg,**/*.JPG,**/*.css" - /> - <uptodate property="local.dist.uptodate" - targetfile="${docs.dist.dir}/doc/faq.html" - > - <!-- use faq as tag file --> - <srcfiles dir="${docs.src.dir}" - includes="${docs.src.pattern}" - /> - </uptodate> - <uptodate property="dist.uptodate" - targetfile="${docs.product.zip}" - > - <!-- use zip as tag file --> - <srcfiles dir="${docs.src.dir}" - includes="${docs.src.pattern}" - /> - <srcfiles dir="${docs.dist.dir}" - includes="${docs.src.pattern}" - /> - </uptodate> - - </target> - - <target name="clean-doc-directories" - depends="init" - description="clean build dirs (including local deploy dir)" - > - <delete quiet="on"> - <fileset dir="${docs.dist.dir}" /> - <fileset dir="${docs.jar.dir}" /> - <fileset dir="${docs.temp.dir}" /> - </delete> - </target> - - <target name="dist" - depends="init,local-dist" - description="create unused doc zip - see ../build/build.xml for installer" - unless="dist.uptodate" - > - <delete file="${docs.product.zip}" /> - <zip zipfile="${docs.product.zip}" - basedir="${docs.dist.dir}" - /> - - <echo message="find doc zip in ${docs.product.zip}" /> - </target> - - <target name="web.deploy.faqonly" - depends="init,faq" - description="deploy docs.dist.dir faq to web.doc.dir" - > - <copy todir="${web.doc.dir}" filtering="on"> - <fileset dir="${docs.dist.dir}/doc" includes="faq.html" /> - </copy> - <stripnonbodyhtml srcdir="${web.doc.dir}" - includes="faq.html" - /> - <echo message="do link check on index and faq before release" - /> - </target> - - <target name="web.deploy.faqindex" - depends="init,dist" - description="deploy built faq and index to web.doc.dir" - > - <copy todir="${web.doc.dir}" filtering="on"> - <fileset dir="${docs.dist.dir}/doc" - includes="faq.html,index.html" - /> - </copy> - <stripnonbodyhtml srcdir="${web.doc.dir}" - includes="faq.html,index.html" - /> - <echo message="do link check on index and faq before release" - /> - </target> - - <target name="web.deploy" depends="web.deploy.README-1.1" /> - - <target name="web.deploy.README-1.1" - depends="init" - description="deploy README-1.1.html to the web site" - > - <property name="readme11.dir" - location="${web.doc.dir}/documentation/readme11" - /> - <mkdir dir="${readme11.dir}" /> - <delete file="${readme11.dir}/index.html" /> - <mkdir dir="${readme11.dir}" /> - <copy tofile="${readme11.dir}/index.html" - file="${aspectj.products.dir}/tools/dist/README-1.1.html" - filtering="on" - /> - <stripnonbodyhtml srcdir="${readme11.dir}" - includes="index.html" - /> - </target> - - <target name="web.deploy.old" - depends="init" - description="deploy built docs to the web site" - > - <mkdir dir="${web.doc.dir}" /> - <delete dir="${web.doc.dir}" /> - <mkdir dir="${web.doc.dir}" /> - <copy todir="${web.doc.dir}"> - <fileset dir="${docs.dist.dir}/doc" /> - </copy> - <stripnonbodyhtml srcdir="${web.doc.dir}" - includes="**/*.html" - /> - </target> - - <!-- ============================================================ --> - <!-- build all doc products --> - <!-- ============================================================ --> - <target name="local-dist" - depends="init" - unless="local.dist.uptodate" - description="avoid local-dist antecedants if uptodate" - > - <antcall target="do-local-dist" /> - </target> - - <target name="do-local-dist" - depends="init,init-filters,faq,devguide,progguide, adk15guide, pdguide" - description="finish products by copying dist files and library sources" - > -<!-- - depends="init,init-filters,api,faq,devguide,progguide, adk15guide, pdguide" ---> - - <copy todir="${docs.dist.dir}" filtering="on"> - <fileset dir="${docs.src.dir}/dist" - excludes="${binary.pattern}" - /> - </copy> - <copy todir="${docs.dist.dir}" filtering="off"> - <fileset dir="${docs.src.dir}/dist" - includes="${binary.pattern}" - /> - </copy> - <available file="${docs.src.dir}/../org.aspectj.lib/build-aspectjlib.xml" - property="org.aspectj.lib.available" - /> - <!--fail unless="org.aspectj.lib.available" - message="unable to find org.aspectj.lib" - /> - <mkdir dir="${docs.dist.dir}/doc/aspectjlib" /> - <copy todir="${docs.dist.dir}/doc/aspectjlib" filtering="off"> - <fileset dir="${docs.src.dir}/../org.aspectj.lib" - includes="build-aspectjlib.xml,src/**" - excludes="CVS" - /> - </copy> - --> - </target> - - <target name="api" - depends="init" - description="javadoc for AspectJ runtime and weaver" - > - <property file="${docs.src.dir}/docs.build.properties" /> - <delete quiet="on"> - <fileset dir="${docs.dist.dir}/doc" includes="*api/*" /> - </delete> - <aspectj-javadoc module="runtime" /> - <aspectj-javadoc module="aspectj5rt"/> - <aspectj-javadoc module="weaver" /> - </target> - - <macrodef name="aspectj-javadoc"> - <attribute name="module" /> - <sequential> - <mkdir dir="${docs.dist.dir}/doc/@{module}-api" /> - <javadoc sourcepath="${@{module}.sourcepath}" - destdir="${docs.dist.dir}/doc/@{module}-api" - windowtitle="AspectJ(tm) @{module} API" - classpath="${@{module}.classpath}" - packagenames="${@{module}.packagenames}" - > - <link offline="true" - href="http://java.sun.com/j2se/1.5/docs/api" - packagelistLoc="${docs.src.dir}/jdk15-packages.txt" - /> - </javadoc> - </sequential> - </macrodef> - - <target name="faq" depends="init"> - <antcall target="xml-html"> - <param name="xml-source-dir" - value="${docs.src.dir}/faq" - /> - <param name="xml-source-root" value="faq.xml" /> - <param name="xsl-source-file" - value="${nochunk.xsl.source}" - /> - <param name="xml-target-dir" value="${docs.dist.dir}" /> - <param name="xml-target-file" - value="${docs.dist.dir}/doc/faq.html" - /> - <param name="xml-html-stylesheet" value="aspectj-faq.css" /> - </antcall> - </target> - - <target name="progguide" depends="init"> - <antcall target="build-guide"> - <param name="guide.dir" value="progguide" /> - <param name="guide.name" value="progguide" /> - <param name="xml-html-copy" - value="dd_arrow.png,aspects.png,figureUML.png,overview.png,telecom.png,aspectj-docs.css"/> - </antcall> - </target> - - <target name="adk15guide" depends="init"> - <antcall target="build-guide"> - <param name="guide.dir" value="adk15notebook" /> - <param name="guide.name" value="adk15notebook" /> - <param name="xml-html-copy" - value="dd_arrow.png,aspectj-docs.css"/> - </antcall> - </target> - - - <target name="devguide" depends="init"> - - <copy todir="${docs.src.dir}/devguide" filtering="off"> - <fileset dir="${devguide.icons.dir}" - includes="${include.devguide.icons}" - /> - </copy> - - <antcall target="build-guide"> - <param name="xml-html-copy" - value="dd_arrow.png,aspectj-docs.css,ajbrowser-building.png,ajbrowser-options.png,${include.devguide.icons}" - /> - <param name="guide.dir" value="devguide" /> - <param name="guide.name" value="devguide" /> - </antcall> - <delete quiet="on"> - <fileset dir="${docs.src.dir}/devguide" - includes="${include.devguide.icons}" - /> - </delete> - </target> - - <target name="pdguide" depends="init"> - - <copy todir="${docs.src.dir}/pdguide" filtering="off"> - <fileset dir="${devguide.icons.dir}" - includes="${include.pdguide.icons}" - /> - </copy> - - <antcall target="build-guide"> - <param name="xml-html-copy" - value="dd_arrow.png,aspectj-docs.css,ajbrowser-building.png,ajbrowser-options.png,${include.pdguide.icons}" - /> - <param name="guide.dir" value="pdguide" /> - <param name="guide.name" value="pdguide" /> - </antcall> - <delete quiet="on"> - <fileset dir="${docs.src.dir}/pdguide" - includes="${include.pdguide.icons}" - /> - </delete> - </target> - - <target name="build-guide" - depends="init" - description="build prog or dev guide, using guide.dir and guide.name" - > - <!-- chunked --> - <antcall target="xml-html"> - <param name="xml-source-dir" - value="${docs.src.dir}/${guide.dir}" - /> - <param name="xml-source-root" value="${guide.name}.xml" /> - <param name="xsl-source-file" - value="${chunk.xsl.source}" - /> - <param name="xml-target-dir" - value="${docs.dist.dir}/doc/${guide.name}" - /> - </antcall> - <!-- single --> - <antcall target="xml-html"> - <param name="xml-source-dir" - value="${docs.src.dir}/${guide.dir}" - /> - <param name="xml-source-root" value="${guide.name}.xml" /> - <param name="xsl-source-file" - value="${nochunk.xsl.source}" - /> - <param name="xml-target-dir" - value="${docs.dist.dir}/doc/${guide.name}" - /> - <param name="xml-target-file" - value="${docs.dist.dir}/doc/${guide.name}/printable.html" - /> - </antcall> - <!-- pdf TODO pdf rendering completes, result is awful - <antcall target="xml-pdf"> - <param name="xml-source-dir" - value="${docs.src.dir}/${guide.dir}"/> - <param name="xml-source-root" value="${guide.name}.xml"/> - <param name="pdf-target-file" - value="${docs.dist.dir}/doc/${guide.name}.pdf"/> - </antcall> - --> - - </target> - - <target name="test-pdf" - depends="init" - description="test pdf build of [prog|dev|adk]guide" - > - <!-- NPE in fop task when building programming guide. - see patch at https://bugs.eclipse.org/bugs/show_bug.cgi?id=81654 - <antcall target="build-pdf"> - <param name="guide.dir" value="progguide" /> - <param name="guide.name" value="progguide" /> - </antcall> - --> - <antcall target="build-pdf"> - <param name="guide.dir" value="adk15notebook" /> - <param name="guide.name" value="adk15notebook" /> - </antcall> - <copy todir="${docs.src.dir}/devguide" filtering="off"> - <fileset dir="${devguide.icons.dir}" - includes="${include.devguide.icons}" - /> - </copy> - - <antcall target="build-pdf"> - <param name="xml-html-copy" - value="ajbrowser-building.png,ajbrowser-options.png,${include.devguide.icons}" - /> - <param name="guide.dir" value="devguide" /> - <param name="guide.name" value="devguide" /> - </antcall> - </target> - - <target name="build-pdf" - depends="init" - description="build prog or dev guide, using guide.dir and guide.name" - > - <antcall target="xml-pdf"> - <param name="xml-source-dir" - value="${docs.src.dir}/${guide.dir}" - /> - <param name="xml-source-root" value="${guide.name}.xml" /> - <param name="pdf-target-file" - value="${docs.dist.dir}/doc/${guide.name}.pdf" - /> - </antcall> - </target> - - <!-- XML conversion stuff --> - - <!-- xml-pdf --> - <target name="xml-pdf"> - <delete file="${pdf-target-file}" /> - <touch file="${pdf-target-file}" /> - <delete file="${xml-source-dir}/index.fo" /> - - <!-- produce index.fo from docbook sources --> - <java classname="com.icl.saxon.StyleSheet" fork="yes"> - <classpath> - <pathelement location="${aspectj.modules.lib.dir}/saxon/saxon.jar" - /> - </classpath> - <arg value="-o" /> - <arg value="${xml-source-dir}/index.fo" /> - <arg value="${xml-source-dir}/${xml-source-root}" /> - <arg value="${aspectj.modules.lib.dir}/docbook/docbook-xsl/fo/docbook.xsl" - /> - </java> - - <!-- index.fo to pdf (TODO if formatting fixed, to init-taskdefs) --> - <taskdef name="fop" - classname="org.apache.fop.tools.anttasks.Fop" - > - <classpath> - <fileset dir="${aspectj.modules.lib.dir}/docbook"> - <include name="fop.jar" /> - <include name="batik.jar" /> - </fileset> - </classpath> - </taskdef> - <!-- TODO messagelevel="info" --> - <fop format="application/pdf" - messagelevel="verbose" - basedir="${guide.dir}" - fofile="${guide.dir}/index.fo" - outfile="${pdf-target-file}" - > - </fop> - <delete quiet="on" file="${guide.dir}/index.fo" /> - </target> - - <target name="xml-html" - description="antcall(xml-source-dir, xml-source-root, xml-target-dir, xml-target-file) - convert xml to html using docbook. parameters: - xml-source-dir # base directory of source - xml-source-root # base file of source (relative to xml-source-dir) - xsl-source-file # xsl transform to apply (use chunk.xsl.source by default) - xml-target-dir # target directory for output (used as xsl param base.dir) - xml-target-file # full path to output file in xml-source-dir, ignored when chunking - xml-html-copy # copy files to target (defaults to *.gif,*.png) - xml-html-stylesheet # style sheet to use (defaults to ${xml-html-stylesheet})" - > - - <mkdir dir="${xml-target-dir}" /> - <copy todir="${xml-target-dir}"> - <fileset dir="${xml-source-dir}" - includes="${xml-html-copy}" - /> - </copy> - <java classname="com.icl.saxon.StyleSheet" - classpath="${aspectj.modules.lib.dir}/saxon/saxon.jar" - fork="yes" - failonerror="yes" - > - <!-- todo: establish failure policy --> - <arg value="-o" /> - <arg value="${xml-target-file}" /> - <arg value="${xml-source-dir}/${xml-source-root}" /> - <arg value="${xsl-source-file}" /> - <arg value="base.dir=${xml-target-dir}/" /> - <arg value="use.id.as.filename=1" /> - <arg value="html.stylesheet=${xml-html-stylesheet}" /> - </java> - </target> - -</project> diff --git a/docs/pom.xml b/docs/pom.xml index c7cea87e5..1f76f17c6 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -163,95 +163,6 @@ </plugins> </build> </profile> - <profile> - <id>create-docs-LEGACY</id> - <activation> - <property> - <name>createDocs_LEGACY</name> - <value>true</value> - </property> - </activation> - - <build> - <resources> - <resource> - <directory>src/main/resources</directory> - <filtering>true</filtering> - <includes> - <include>**/local.properties</include> - </includes> - </resource> - </resources> - - <pluginManagement> - <plugins> - <!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself.--> - <plugin> - <groupId>org.eclipse.m2e</groupId> - <artifactId>lifecycle-mapping</artifactId> - <version>1.0.0</version> - <configuration> - <lifecycleMappingMetadata> - <pluginExecutions> - <pluginExecution> - <pluginExecutionFilter> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-antrun-plugin</artifactId> - <versionRange>[1.7,)</versionRange> - <goals> - <goal>run</goal> - </goals> - </pluginExecutionFilter> - <action> - <ignore></ignore> - </action> - </pluginExecution> - </pluginExecutions> - </lifecycleMappingMetadata> - </configuration> - </plugin> - </plugins> - </pluginManagement> - - <plugins> - <plugin> - <artifactId>maven-antrun-plugin</artifactId> - <version>3.0.0</version> - <executions> - <execution> - <id>make-docs</id> - <phase>process-resources</phase> - <configuration> - <target> - <copy - file="${project.build.outputDirectory}/local.properties" - toFile="../build/local.properties" - overwrite="true" - /> - <ant antfile="build.xml"> - <target name="dist"/> - </ant> - </target> - </configuration> - <goals> - <goal>run</goal> - </goals> - </execution> - </executions> - </plugin> - </plugins> - - </build> - - <dependencies> - <dependency> - <!-- All modules referencing files inside 'lib' need this dependency --> - <groupId>org.aspectj</groupId> - <artifactId>lib</artifactId> - </dependency> - </dependencies> - - </profile> </profiles> </project> diff --git a/docs/readme-docs-module.adoc b/docs/readme-docs-module.adoc index 523912921..d7d236749 100644 --- a/docs/readme-docs-module.adoc +++ b/docs/readme-docs-module.adoc @@ -17,101 +17,3 @@ works: guides `quickref/quick.pdf` and `quickref/quickA4.pdf`. * `build.xml`: Ant build script for the doc distribution * `developer`: Docs for AspectJ developers - -*Build*: `build.xml` assembles a local distribution which is gathered -into the product distribution by the master build script, -`../build/build.xml`. Dependencies outside this directory: - -* `.xml` files refer to their docbook dtds using relative path, for the - moment `../../lib/docbook/...` -* When building docbook, uses `../lib/saxon` libraries. -* When building installer, using `../lib/build/build.jar` and the - `../build/installer-resources`. -* `quickref/quick.pdf` is generated manually from `quickref/quick.doc`. -* `../org.aspectj.lib` provides library sources for - `{AspectJ}/doc/aspectjlib`. - -When editing the build script and XML files, try to make only -substantive changes rather than reformatting, which produces illusory -changes. If you do reformat, do so programmatically (e.g., using -XMLBuddy plugin reformat command, with long lines wrapped and 80 -character lines). - -== Docbook notes - -#*TODO:* Remove this section after AsciiDoc conversion is complete# - -Documentation is written in docbook XML form, which is transformed to -HTML (single-page and multi-page forms) and, potentially, PDF. -Unfortunately, this means you need to use the tags which are not only -legal, but which work when transformed into all output formats, even if -it means working around bugs in the transform scripts. Following are -some notes on traps to avoid. - -=== Authoring support - -XMLBuddy has a free eclipse plugin that displays errors using problem -items and gutter annotations, but it gets confused by entity references. -So for devguide.xml, create a new file foo.xml and do a manual merge, -correct the files, and then scatter again (leo?). - -=== PDF transformation - -The transformation from docbook XML to formatting-objects (.fo) -to pdf is fairly weak. If you run the build.xml `test-pdf` task, -you'll see a number of debug messages, which unfortunately give no -clue as to the location of the problem. Problems noted in the output -(where DE == docbook element) - -* tables broken. -** DE `table` unsupported -** DE `informaltable` autolayout is not supported -* lineation/justification broken -* need things like page header/footer titles, page number, copyright -* Valid docbook elements not supported: -** superscript in title -* ... - -Sample debug messages: - -- `area contents overflows area in line` -- `table-layout=auto is not supported, using fixed!` -- `The element 'fo:table-and-caption' is not yet implemented.` - (So use docbook element (DE) `informaltable`, not DE `table`.) -- `No spaces to justify text in line` many times - -== Older notes - -=== Misc info for writing and building docbook - -* link tag linkend attribute takes an id -** xsl converts as needed during output -** do NOT use `ulink`; this will be converted to `""` - (but see param `citerefentry-link`: might enable this) - -* to use sensible names for the files produced, -** use an xsl wrapper to add/modify features -** set flag to use the id of the top-level element in the output - file as the filename. + - `xsl:param name="use.id.as.filename" select="1"` -** fyi, other related parameters: `html-ext`, `root-filename` -** In this example, the top-level element in the output file - is the `refentry`, so set ids which become the basename of the file: + -+ - refentry id="aspectj-mode" # in aspectj-mode.xml, produces aspecj-mode.html - refentry id="ajdee" # in ajdee.xml, produces ajdee.html - -** related parameters: `html-ext`, `root-filename` -** these tags did not work for me: `dbhtml filename="foo.htm"`, `dbhtml prefix="foo-"` - -== Resources - -- the dtd reference for docbook - http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html -- the stylesheet reference for docbook xsl - http://docbook.sourceforge.net/projects/dsssl/doc/html.html - -== To Do - -- fyi, generate.reference.titlepage appears not to be respected. - tried to add if statement to html/refentry.xsl, but file still gen'd diff --git a/docs/src/main/resources/local.properties b/docs/src/main/resources/local.properties deleted file mode 100644 index a3cd6d2fe..000000000 --- a/docs/src/main/resources/local.properties +++ /dev/null @@ -1,12 +0,0 @@ -# for non-release builds, versions should all be DEVELOPMENT -# except for build.version.base -build.version=${project.version} -build.version.base=1.5 -build.version.long=${project.version} -build.version.short=${project.version} -# Repo version is for maven (as built with 'ant repo') -repo.version=1.6.4 -java11.home=c:/home/apps/jdk11 -java13.home=c:/home/apps/jdk13 -java14.home=c:/home/apps/jdk14 -java15.home=c:/home/apps/jdk15 |