ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicolas Lalevée <nicolas.lale...@hibnet.org>
Subject Re: Ivy documentation with asciidoc
Date Wed, 31 May 2017 15:32:38 GMT

> Le 31 mai 2017 à 15:34, J Pai <jai.forums2013@gmail.com> a écrit :
> 
> One thing I just noticed in the generated adoc files is that “external” links that
are part of the original xooki backed .html files are not being generated as links in the
converted adoc. To see a couple of example, take a look at this hibnet.org/tmp/ivy-asciidoc/index.html
page. The “Apache License” in this sentence:
> 
>> Ivy is open source and released under a very permissive Apache License.
>> 
> 
> 
> and the “features” in :
> 
>> Ivy has a lot of powerful features
> 
> are actually link references in the original xooki backed docs of the form [[license
Apache License]] and [[features]].

It seems that xooki doesn’t generate links either:
http://ant.apache.org/ivy/history/trunk/index.html <http://ant.apache.org/ivy/history/trunk/index.html>

Probably the pointed pages have been deleted or moved and these links have not been updated.

Nicolas

> 
> -Jaikiran
> 
> On 31-May-2017, at 6:50 PM, J Pai <jai.forums2013@gmail.com> wrote:
> 
> I had some time today and decided to test this branch out locally. I was able to generate
the docs without any hassle. The conversion works fine which is a great thing.
> 
> There are certain warning about the heading/section level we use in the generated adoc
files, for top level heading:
> 
>> [asciidoctor:convert] asciidoctor: WARNING: dependency.adoc: line 7: section title
out of sequence: expected level 1, got level 2
> 
> 
> but that’s pretty much it in terms of build time warnings/errors.
> 
> In one of my other mails I had noted that if not in this release then maybe in next release
we can focus on this xooki to asciidoc conversion. But at that time I wasn’t aware that
Nicolas had already done the bulk of this job by implementing this tool. 
> 
> So IMO, after fixing/finalizing some of those WARN related issues, we can probably just
go ahead and use this tool to convert our current docs to adoc as a one time thing in our
master branch. Till we are comfortable and are sure that the conversion is done fully, we
can keep the old xooki backed docs as-is but just not update/add any new stuff in them. Given
how nicely this tool works and the fact that it isn’t breaking anything, I don’t think
we will have to maintain a separate branch to deal with this migration.
> 
> Any thoughts?
> 
> -Jaikiran
> 
> On 25-May-2017, at 7:55 PM, Nicolas Lalevée <nicolas.lalevee@hibnet.org> wrote:
> 
> 
>> Le 25 mai 2017 à 16:17, Matt Sicker <boards@gmail.com> a écrit :
>> 
>> Merge commits always spam the commits list which, while annoying, I've
>> learned to mass-delete whenever it happens. ;)
>> 
>> I looked at some random changes and found a couple markup typos, but
>> otherwise it looks like it converted well enough.
> 
> Yes, I have stopped one too. Some things will need to be manually fixed after the automatic
conversion.
> 
>> I'm more familiar with the maven plugins for site management, so I'm not
>> sure about the integration aspects, but worst case scenario, can't you just
>> commit the parts to svnpubsub on release?
> 
> If you look at the menu on the left, it is present on each page, so it means that for
any new file or deleted file, every page has to be regenerated. The consequence it that generating
a page of the site has to be aware of the list of all the pages of the documentation.
> 
> But we can imagine that we uncouple the documentation, like it is being done for the
old versions of the documentation, in the « history » section, by just having a link. So
yes we could some manual copy and publish to svnpubsub on release.
> 
> Nicolas
> 
>> 
>> On 25 May 2017 at 09:00, Nicolas Lalevée <nicolas.lalevee@hibnet.org> wrote:
>> 
>>> I have updated the branch xooki2asciidoc. The merge generated 50 emails,
>>> which I still find weird, I would expect just one mail about the commit of
>>> the merge.
>>> 
>>> I can see the current status of the transformation of the xooki source
>>> into asciidoc source and then the generated html from that here:
>>> http://hibnet.org/tmp/ivy-asciidoc/index.html <http://hibnet.org/tmp/ivy-
>>> asciidoc/index.html>
>>> 
>>> It seems pretty good, but I didn’t looked to most of the pages.
>>> 
>>> Before going further, we need to figure out how it would be integrated to
>>> the website since it is also managed by xooki. The site and the
>>> documentation are tidily coupled by the toc which is managed by xooki.
>>> 
>>> Nicolas
>>> 
>>> 
>> 
>> 
>> -- 
>> Matt Sicker <boards@gmail.com>
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
> For additional commands, e-mail: dev-help@ant.apache.org
> 
> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
> For additional commands, e-mail: dev-help@ant.apache.org
> 


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message