Convert documentation to AsciiDoc #273
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Some originals have been deleted already. Others, especially the user guides, still exist in both formats because they have not been proof-read and probably lots of links do not function as expected. But I want to see what the files look like directly on GitHun. Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
- Add Java syntax highlighting to AspectJ and Java files - Add XML syntax highlighting to XML files (Ant, LTW etc.) - Dedent and remove empty lines, where necessary - Enclose in-line line numbers for Java code in /*23*/ comments in order to enable Java formatting Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Also unify the way copyright and release date is displayed Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
- The website is just a front page.
- I failed to contact anyone via:
* fb9553b7471df638478bbf918044bf52.gdrp@customers.whoisprivacycorp.com
* [email protected]
* [email protected]
- The [email protected] mailing list had its last post 6 years ago and
the last one concerning AspectJ 11 years ago according to the archive
at https://discuss.aosd.narkive.com/.
Mention Spring support for native AspectJ an Spring AOP as a real world
example in the FAQ.
Also remove an FAQ link to a no longer existing PARC website about
AspectJ and fix a small typo.
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
and fix some minor punctuation issues in older release notes. Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
To do: - API docs (javadoc) - all-in-one guides - Eclipse website links - add links to markdown files (maybe convert md to adoc) Signed-off-by: Alexander Kriegisch <[email protected]>
User relative paths for images instead. In one case, we need to copy images from a subdirectory one level up, because otherwise the images are only found in the included document, but not in the single-page one including it from the subdirectory. In all other cases, included ADOCs are located in the same directory as the including document. Signed-off-by: Alexander Kriegisch <[email protected]>
- AspectJ Browser (ajbrowser) - Forte IDE integration - JBuilder IDE integration - Emacs integration All this information was old and outdated. Ajbrowser was removed from AspectJ a while ago. If the other tools even still exist, any possibly existing AspectJ support is not part of AspectJ itself. Signed-off-by: Alexander Kriegisch <[email protected]>
- Link to other pages in index.adoc - Include other pages in design-overview.adoc Signed-off-by: Alexander Kriegisch <[email protected]>
In each case, link both to multi- and single-page docs separately. Signed-off-by: Alexander Kriegisch <[email protected]>
in favour of the already existing asciidoc ones. Signed-off-by: Alexander Kriegisch <[email protected]>
Also rename references. E.g. - RELEASE-11 -> RELEASE-1.1 - RELEASE-1810 -> RELEASE-1.8.10 - RELEASE-1921 -> RELEASE-1.9.21 Signed-off-by: Alexander Kriegisch <[email protected]>
kriegaex
added
documentation
kriegaex
force-pushed
the
docs-to-asciidoc
branch
from
95563b1 to
d8a1fc7
Compare
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Also rename ADOC on the way and move images to subdirectory. This makes the Maven Resource execution superfluous. TODO: Adjust image links in compiler-weaver.adoc in next commit. Signed-off-by: Alexander Kriegisch <[email protected]>
After move in previous commit, now the paths have been fixed, too. Signed-off-by: Alexander Kriegisch <[email protected]>
to match the GIF file names, so it is easy to recognise which Visio file was used to create which GIF, even if no Visio viewer is available. Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Warning "Native subprocess control requires open access to the JDK IO subsystem" can be avoided by upgrading JRuby, see asciidoctor/asciidoctor-maven-plugin#553. Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
The files are still GIFs for now. In the next steps after the rename, they will be replaced by real PNGs. Background: The Asciidoctor PDF back-end cannot handle GIFs directly without an additional Ruby Gem. It is easier to only use PNGs and JPEGs. Signed-off-by: Alexander Kriegisch <[email protected]>
Follow-up on previous rename-only commit. This time, the binaries are real PNGs. The asciidoc and other references to them have also been replaced. File figures_classes.png in the teaching materials also was rotated by 90° to display it correctly. Background: The Asciidoctor PDF back-end cannot handle GIFs directly without an additional Ruby Gem. It is easier to only use PNGs and JPEGs. Signed-off-by: Alexander Kriegisch <[email protected]>
Using Asciidoctor Maven, we now produce PDFs (which are also linked to from the main documentation index page) for - Programming Guide, - AspectJ 5 Developer's Notebook, - Development Environment Guide, - Problem Diagnosis Guide, - AspectJ Design Overview. Attention! PDF generation alone takes 3+ minutes, almost 4 minutes including asciidoc to HTML conversion. Just deactivate the 'create-docs' profile if you do not need docs during the build. Closes #272. Signed-off-by: Alexander Kriegisch <[email protected]>
The Docbook etc. Ant task profile is now called 'create-docs-LEGACY' and will go away with the cut-over to the new doc generator logic. Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
When extracting text or HTML files, special characters like German umlauts "ÄÖÜäöüß" or copyright symbol "©" were destroyed while unpacking the installer archive. As our files in Git SCM are all UTF-8, the installer now also uses UTF-8 to read and write text files. Fixes #270. Signed-off-by: Alexander Kriegisch <[email protected]>
TODO: There still is one set of CSS files per subdirectory due to the way the docs directories are organised. It would be better to have them just once. But to achieve that, the ADOC-to-HTML conversion would have to be changed, e.g. using one central directory for images and reorganisation of the overall directory structure and build options. See asciidoctor/asciidoctor-maven-plugin#729. Signed-off-by: Alexander Kriegisch <[email protected]>
Closes #271. Signed-off-by: Alexander Kriegisch <[email protected]>
If we ever decide to add Maven site docs to the AspectJ website, now we can deploy them locally using 'mvn site:deploy' and publish them on a web server or even incorporate them into the binary distribution in the installer's belly. Signed-off-by: Alexander Kriegisch <[email protected]>
Along with the Ant and Maven build configs, downloads of - DocBook DTD, - DocBook XSL, - FOP, - Batik, - Saxon also become obsolete. Signed-off-by: Alexander Kriegisch <[email protected]>
In the next step, the content, which is still HTML at this point, is going to be converted. Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
kriegaex
force-pushed
the
docs-to-asciidoc
branch
from
d8a1fc7 to
db97607
Compare
Like the javadocs in aspectjrt and aspectjweaver (if the releas profile is active), for docs also copy the docs in the package phase to the aj-dist directory. Signed-off-by: Alexander Kriegisch <[email protected]>
Signed-off-by: Alexander Kriegisch <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Closes #76.