<div dir="ltr">I've looked for a few tools, but hadn't seen this one yet. Looks kind of promising though. If I could figure out how to export the docs to DocBook I'd test it :)</div><div class="gmail_extra"><br><div class="gmail_quote">On Fri, May 13, 2016 at 1:26 PM, Brian Stansberry <span dir="ltr"><<a href="mailto:brian.stansberry@redhat.com" target="_blank">brian.stansberry@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Has anyone used a good docbook to asciidoc converter, e.g. the docbookrx<br>
discussed at [1] or the O'Reilly thing at [2]?<br>
<br>
If we can't have some sort of reasonable conversion it's hard to imagine<br>
us making the move.<br>
<br>
[1]<br>
<a href="https://blogs.gnome.org/pmkovar/2015/10/27/converting-docbook-into-asciidoc/" rel="noreferrer" target="_blank">https://blogs.gnome.org/pmkovar/2015/10/27/converting-docbook-into-asciidoc/</a><br>
<br>
[2] <a href="https://github.com/oreillymedia/docbook2asciidoc" rel="noreferrer" target="_blank">https://github.com/oreillymedia/docbook2asciidoc</a><br>
<span class=""><br>
On 5/13/16 10:46 AM, James Perkins wrote:<br>
> Yeah I think I prefer approach 3 myself. It just might be a lot of work<br>
> to get there.<br>
><br>
> I was thinking we could either use the gh-pages/<a href="http://github.io" rel="noreferrer" target="_blank">github.io</a><br>
</span>> <<a href="http://github.io" rel="noreferrer" target="_blank">http://github.io</a>> approach or even just make it part of the <a href="http://wildfly.org" rel="noreferrer" target="_blank">wildfly.org</a><br>
> <<a href="http://wildfly.org" rel="noreferrer" target="_blank">http://wildfly.org</a>> [1] repo in a docs subdirectory. I see it being<br>
<span class="">> nice in some ways having it on <a href="http://wildfly.org" rel="noreferrer" target="_blank">http://wildfly.org</a>.<br>
><br>
> [1]: <a href="https://github.com/wildfly/wildfly.org" rel="noreferrer" target="_blank">https://github.com/wildfly/wildfly.org</a><br>
><br>
> On Fri, May 13, 2016 at 6:12 AM, David M. Lloyd <<a href="mailto:david.lloyd@redhat.com">david.lloyd@redhat.com</a><br>
</span><div><div class="h5">> <mailto:<a href="mailto:david.lloyd@redhat.com">david.lloyd@redhat.com</a>>> wrote:<br>
><br>
> I like approach 3, assuming that it'll move in to e.g. GitHub. If<br>
> there's an update to a doc, it's a lot easier to backport using git than<br>
> Confluence. Less chance of old docs getting abandoned, and easier for<br>
> users to contribute fixes and updates if they can just open a PR for<br>
> each affected version. We're already reasonably well-trained to deal<br>
> with old branches.<br>
><br>
> I don't know how we'd organize it though; I've never done multi-document<br>
> things using asciidoc, and also we'd have to publish it somehow<br>
> (preferably in an automated manner).<br>
><br>
> On 05/12/2016 10:32 PM, James Perkins wrote:<br>
> > I've been reading the WildFly documentation [1] quite a bit lately and<br>
> > noticing a lot of issues. Sometimes it references WildFly 8 in the<br>
> > WildFly 10 (or 9) documentation. Sometimes it references JBoss AS 7.<br>
> > Links take you to old documentation, e.g. a WFLY10 doc takes you to a<br>
> > page for WFLY8. Sometimes documentation is just plain out of date<br>
> > referencing behavior that has possibly been removed or replaced by<br>
> > something better.<br>
> ><br>
> > This has happened because we keep copying the documentation over each<br>
> > time we have a new version. Overall this makes sense as a lot of it<br>
> > doesn't need to be changed. However it leaves reading the<br>
> documentation<br>
> > confusing. Reading documentation for WildFly 10 and seeing WildFly<br>
> 8 in<br>
> > the text with a link for AS72 isn't very user friendly as I'm sure we<br>
> > can all agree.<br>
> ><br>
> > There's a few different ways we could go with this.<br>
> ><br>
> > Approach 1:<br>
> > One, probably the easiest, is to use a single confluence project. We'd<br>
> > need to remove the version numbers from the text, which I think we<br>
> > should do anyway. Instead of referencing WildFly 10 we just<br>
> reference it<br>
> > as WildFly.<br>
> ><br>
> > An issue I can think of with this approach is some how annotating or<br>
> > referencing that parts of the documentation only work with ${version}.<br>
> > For example new features would have to be noted they only work with<br>
> > ${version}+.<br>
> ><br>
> ><br>
> > Approach 2:<br>
> > Essentially he same as approach 1 only do allow different Confluence<br>
> > projects for the different Java EE target version. So WIldFly 8, 9 and<br>
> > 10 would all be documented under something like WFLYEE7.<br>
> ><br>
> > Approach 3<br>
> > Switch to using something like asciidoc which can use variables and<br>
> > generate links to the correct content. While this approach is probably<br>
> > takes the most work up front, it seems like like it would be easier to<br>
> > maintain between releases.<br>
> ><br>
> > Any other suggestions are welcome.<br>
> ><br>
> > [1]: <a href="https://docs.jboss.org/author/display/WFLY10/Documentation" rel="noreferrer" target="_blank">https://docs.jboss.org/author/display/WFLY10/Documentation</a><br>
> ><br>
> > --<br>
> > James R. Perkins<br>
> > JBoss by Red Hat<br>
> ><br>
> ><br>
> > _______________________________________________<br>
> > wildfly-dev mailing list<br>
</div></div>> > <a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a> <mailto:<a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a>><br>
<span class="">> > <a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/wildfly-dev</a><br>
> ><br>
><br>
> --<br>
> - DML<br>
> _______________________________________________<br>
> wildfly-dev mailing list<br>
</span>> <a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a> <mailto:<a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a>><br>
<span class="im HOEnZb">> <a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/wildfly-dev</a><br>
><br>
><br>
><br>
><br>
> --<br>
> James R. Perkins<br>
> JBoss by Red Hat<br>
><br>
><br>
</span><span class="im HOEnZb">> _______________________________________________<br>
> wildfly-dev mailing list<br>
> <a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a><br>
> <a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/wildfly-dev</a><br>
><br>
<br>
<br>
--<br>
</span><span class="HOEnZb"><font color="#888888">Brian Stansberry<br>
Senior Principal Software Engineer<br>
</font></span><div class="HOEnZb"><div class="h5">JBoss by Red Hat<br>
_______________________________________________<br>
wildfly-dev mailing list<br>
<a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/wildfly-dev</a><br>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div>James R. Perkins</div><div>JBoss by Red Hat</div></div></div></div></div>
</div>