Community
Participate
Working Groups
The help contents generation provided by org.eclipse.gef4.releng based on Mylyn wikitext still needs to be improved with respect to the following: - Local anchor links are currently broken. - References to javadoc need to be rewritten to point to the offline-linked version, if applicable. - References to help wiki pages of other GEF4 components need to be rewritten to point to the local help, provided by the doc bundle of the respective component (internalLinkPattern would have to be adjusted accordingly, probably via a custom extension, as different doc bundles are responsible for different components). - The libraries checked into o.e.g4.releng/libs should rather be pulled in via dependencies.
I have added a message to the Mylyn forum to investigate how the local anchor links can be fixed: https://www.eclipse.org/forums/index.php?t=msg&th=1066480&goto=1695108&#msg_1695108.
Furthermore, the styling should be adjusted to at least re-use the code styling from the Eclipse wiki.
It seems the broken anchor links are caused by two issues: bug #467067 (local links that are specified absolute are not properly extracted) and bug #467068 (local links to headings with special chars are not properly extracted). While we can ensure all our local links are specified relative to work around bug #467067, the second problem does not seem to be as easy to solve.
I investigated to re-use the stylesheets from wiki.eclipse.org, so the offline documentation looks similar. However, due to bug #467914 we cannot include references to the online stylesheet, and I am not sure whether we can provide a local offline copy (have to check this with eom-ip-team). As such, the original stylesheet can currently not be used. Also, the wikitext extraction does seem to loose the styling classes used for source code highlighting, so that in the extracted documentation the syntax highlighting is lost.
Added URL-rewriting to ensure that references to platform javadoc are rewritten to point to local org.eclipse.platform.doc.isv bundle (independent of version that was linked).
Added local book.css stylesheet to all GEF4 doc bundles, which refers to the global book.css as follows: @import "../PRODUCT_PLUGIN/book.css"; We could alternatively use the same styling as within the online wiki documentation, by using the following contents: @import "http://wiki.eclipse.org/skins/solstice/public/stylesheets/styles.min.css"; body { padding:10px; } This IMHO looks nicer, but it is not in line with the Eclipse doc styling guidelines (https://wiki.eclipse.org/Eclipse_Doc_Style_Guide#CSS_Class_Summary), so we have to check before if this would be tolerable.
Updated Mylyn wikitext librararies to 2.6.0.N20150724 nightly build to fix that links to anchors with special chars were broken (see bug #467067).
Two things should still be resolved here: 1) References to help wiki pages of other GEF4 components need to be rewritten to point to the local help, provided by the doc bundle of the respective component, if it is installed. I raised bug #469233 to request that an alternative url can be specified. We could implemented URL rewriting if this was supported. 2) The libraries checked into o.e.g4.releng/libs should rather be pulled in via dependencies. We could use Maven dependency mechanism to resolve this.
Updated to wikitext 2.7.0.N20151009-1723 to consume fix for bug #468609, so that __NO_TOC__ is suppressed during reference doc generation.
While the documentation is transferred to the GibtHub wiki, the remaining issues named in comment #8 still hold there as well, so adding a reference.
There is an additional third issue (that seems to hold for mediawiki and markdown, so its no regression introduced by migrating the documentation to the Github wiki). It seems that the HTML pretty-printer adds link blocks on a new line each. This is problematic if a link is enclosed within brackets, as the browser will insert a space before the link. For instance, the following output is produced as part of the Common documentation: <p>The <a href="Common.html#dispose">Dispose</a> package provides an abstraction ( <a href="Common.html#idisposable">IDisposable</a>) for objects that need to be notified when being disposed. </p> It is invalidly rendered as: The Dispose package provides an abstraction ( IDisposable) for objects that need to be notified when being disposed.
