[JBoss JIRA] (TOOLSDOC-492) Create new docs landing page on new tools.jboss.org site (moving to asciidoc for docs in process)
3:22 a.m.
[
https://issues.jboss.org/browse/TOOLSDOC-492?page=com.atlassian.jira.plug...
]
Nick Boldt edited comment on TOOLSDOC-492 at 5/7/14 4:21 AM:
-------------------------------------------------------------
New issues:
HTML from Docbook:
{code:title=}view-source:https://docs.jboss.org/tools/nightly/trunk/en/User_Guide/html_single/index.html}
These wizards create the same project using different underlying technology, as stated in
the project name. To view a project summary, hover the cursor over a project wizard. If
you do not have the necessary plug-in installed to use a wizard, you are prompted to
install it when you click the wizard.
</p><div class="figure"><a
id="d0e457"/><div class="figure-contents"><div
class="mediaobject"><img src="images/3963.png" alt="The
Start from scratch wizards create the same project using different underlying technology,
as started in the project name. To view a project summary, hover the cursor over a project
wizard."/></div></div><p class="title"><b>Figure
1.1. Start from Scratch Wizards</b></p></div><br
class="figure-break"/></dd><dt><span
class="term"><span class="guilabel"><strong>Start from
a sample</strong></span></span></dt><dd><p>
{code}
HTML from docbook converted to adoc via pandoc (images are broken, with incomplete alt
tags and invalid height/width attribs, and no figure captions):
{code:title=view-source:file:///home/nboldt/eclipse/workspace-jboss/jbosstools-github-master/jbosstools-documentation/userguide/target/generated-docs/readme.html#customizing-openshift-tools}
<p>These wizards create the same project using different underlying
technology, as stated in the project name. To view a project summary,
hover the cursor over a project wizard. If you do not have the
necessary plug-in installed to use a wizard, you are prompted to
install it when you click the wizard.</p>
<div class="paragraph">
<p><span class="image"><img src="./images/3963.png"
alt="The <code>Start from scratch</code> wizards create the same project
using different underlying technology" width="as started in the project name. To
view a project summary" height="hover the cursor over a project
wizard."></span></p>
</div>
{code}
was (Author: nickboldt):
New issues:
HTML from Docbook:
{code:title=}view-source:https://docs.jboss.org/tools/nightly/trunk/en/User_Guide/html_single/index.html}
These wizards create the same project using different underlying technology, as stated in
the project name. To view a project summary, hover the cursor over a project wizard. If
you do not have the necessary plug-in installed to use a wizard, you are prompted to
install it when you click the wizard.
</p><div class="figure"><a
id="d0e457"/><div class="figure-contents"><div
class="mediaobject"><img src="images/3963.png" alt="The
Start from scratch wizards create the same project using different underlying technology,
as started in the project name. To view a project summary, hover the cursor over a project
wizard."/></div></div><p class="title"><b>Figure
1.1. Start from Scratch Wizards</b></p></div><br
class="figure-break"/></dd><dt><span
class="term"><span class="guilabel"><strong>Start from
a sample</strong></span></span></dt><dd><p>
{code}
HTML from docbook converted to adoc via pandoc (images are broken, with incomplete alt
tags and invalid height/width attribs):
{code:title=view-source:file:///home/nboldt/eclipse/workspace-jboss/jbosstools-github-master/jbosstools-documentation/userguide/target/generated-docs/readme.html#customizing-openshift-tools}
<p>These wizards create the same project using different underlying
technology, as stated in the project name. To view a project summary,
hover the cursor over a project wizard. If you do not have the
necessary plug-in installed to use a wizard, you are prompted to
install it when you click the wizard.</p>
<div class="paragraph">
<p><span class="image"><img src="./images/3963.png"
alt="The <code>Start from scratch</code> wizards create the same project
using different underlying technology" width="as started in the project name. To
view a project summary" height="hover the cursor over a project
wizard."></span></p>
</div>
{code}
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/scen... 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/documentatio...
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)
4363
days inactive
4363
days old
jbosstools-issues@lists.jboss.org
0 comments
1 participants
participants (1)
-
Nick Boldt (JIRA)