[jbosstools-issues] [JBoss JIRA] (TOOLSDOC-492) Create new docs landing page on new tools.jboss.org site (moving to asciidoc for docs in process)

[Michelle Murray (JIRA)]

    [ https://issues.jboss.org/browse/TOOLSDOC-492?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12967687#comment-12967687 ] 

Michelle Murray commented on TOOLSDOC-492:
------------------------------------------

Michelle's Asciidoc review of 
https://github.com/nickboldt/jbosstools-documentation/tree/TOOLSDOC_492_3/userguide/src/main/asciidoc

*Summary*: Works great! Good enough to use.

*Minor issues to be fixed manually:*
* BrowserSim 3.2 first para is funny text (wrong indent?)
* HMT 2.2 proc numbering is off - too many varied nested lists
* HMT 2.7 proc numbering is off and inc *
* Central 3.5 proc title ends up in important
* Server 2.4 & 2.5 proc numbering is off - too many varied nested lists and inc +
* OS Fig19 missing
* OS 2.13 important box includes too much - so other variable list items and what should be '3. Customizing' and subsections aren't rendered
* in variable lists should indent images/figs too - figs in proc steps & substeps are

*Github rendering/css limitations to be aware of [all are rendered fine with Asciidoctor.js]:*
* important and note, inc. images
* Proc and Fig headings
* 'See also' link don't work
* Lists with lowercase alpha enumeration (used for alternative steps in procs) render as i, ii  [but a, b as expected with Asciidoctor.js]

*Import to PressGang (& conversion back to DocBook) issues:*
* Stop import
** tags in image alt text (e.g., <div>) - just 1 instance caused problem, but just need to avoid using tags in alt text in future
* Stop book production
** 'See also' links break - not unexpected, will submit PG RFE to see if can be fixed
** [file]`filename` converts to <literal><phrase role="file">filename</phrase></literal> and literal doesn't have <phrase> as child - in future just have filenames as literals, so `filename`

> Create new docs landing page on new tools.jboss.org site (moving to asciidoc for docs in process)
> -------------------------------------------------------------------------------------------------
>
>                 Key: TOOLSDOC-492
>                 URL: https://issues.jboss.org/browse/TOOLSDOC-492
>             Project: Documentation for JBoss Tools and Developer Studio
>          Issue Type: Bug
>      Security Level: Public(Everyone can see) 
>          Components: User Guide
>    Affects Versions: 4.2.0.Beta1
>            Reporter: Nick Boldt
>            Assignee: Michelle Murray
>             Fix For: 4.2.0.Beta2
>
>         Attachments: asciidoc-to-html5-with-sidebar-toc.png, converted-adoc-asciidoc-css-not-github-css.png, converted-adoc-github-css-actual.png, converted-adoc-github-css.png, openshift-chapter-generated-epub.png, openshift-chapter-generated-pdf.png, xref-do-not-render.png
>
>
> With the release of the new tools.jboss.org site, it's time to migrate the docs to the same skin / format / markup. Docbook is dead, long live Asciidoc!
> What [~mmurray] and I are thinking is that we would have a new landing page similar to one of these:
> http://tools.jboss.org/features/ (with icons that link to projects' latest doc)
> or
> http://tools.jboss.org/documentation/whatsnew/ (with the latest doc linked)
> And then under that landing page we'd have doc for each of projects' contributions to the User Guide, by milestone or Final release.
> Questions:
> a. [~maxandersen] [~burrsutter] [~mmusaji] Do we still need to provide 3 formats of doc - HTML, HTML-single, and PDF? Or can we replace that with this new content, PLUS include inline help doc within Eclipse? (That's another issue - see [~dgolovin] 's https://github.com/dgolovin/jbosstools-eclipse-docs/blob/master/docs/scenarios.md for prototype)
> b. [~maxandersen] Should we include docs for "dead" projects like Freemarker, Portal, etc.? I'm guessing YES, even if the doc becomes out of date (ie., the doc for JBT 4.2 for Freemarker won't have changed much (or at all) since JBT 4.0/4.1).
> c. [~maxandersen] Should we convert old JBT 4.1.x (and/or 4.0.x, 3.3.x) doc to the new adoc format, or just start w/ the JBT 4.2.0.Beta1/2 doc? I'd be OK with 4.1 and maybe 4.0, but can we skip 3.3 since JBDS 5 is no longer fully supported?
> d. Will docbook2asciidoc [0] work for batch-converting docbook docs to adoc? @nick will try. If conversion works easily, then converting older User Guides is definitely more doable / less time consuming.
> [0] https://github.com/oreillymedia/docbook2asciidoc
> e. [~xcoulon] Is :page-component_version: still used, eg., in [1], or is the filename version itself used to categorize the content by milestone?
> [1] https://github.com/jbosstools/jbosstools-website/blob/master/documentation/whatsnew/openshift/openshift-news-2.6.0.Beta1.adoc
> f. If we decide to continue to include other formats (eg., html-single, pdf) should we link to those from these places [2], [3]?
> [2] http://tools.jboss.org/downloads/overview.html
> [3] http://tools.jboss.org/downloads/jbosstools/luna/4.2.0.Beta1.html



--
This message was sent by Atlassian JIRA
(v6.2.3#6260)