Mailing-List: contact dev-help@ant.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Ant Developers List" <dev@ant.apache.org>
From: =?utf-8?Q?Nicolas_Lalev=C3=A9e?= <nicolas.lalevee@hibnet.org>
Content-Type: multipart/alternative;
 boundary="Apple-Mail=_2B944D52-60BF-4E85-8E16-1ACBB7AD2747"
Mime-Version: 1.0 (Mac OS X Mail 10.3 \(3273\))
Subject: Re: Ivy documentation with asciidoc
Date: Wed, 31 May 2017 17:32:38 +0200
References: <CABEA4F3-93CD-4FD9-9D60-2B08C474D051@hibnet.org>
 <CACmp6kpi5G_fVLyC=fOZZ47qQStdz2SS3nEvPw90Q4rSTjdB_A@mail.gmail.com>
 <06C5903F-75F0-4E17-B0A1-BE7D36A5E3D0@hibnet.org>
 <74DBEF36-60F9-43C7-9484-683A4E4CEF8B@gmail.com>
 <AB120E96-39EF-48B0-805D-7D7F75096216@gmail.com>
To: Ant Developers List <dev@ant.apache.org>
In-Reply-To: <AB120E96-39EF-48B0-805D-7D7F75096216@gmail.com>
Message-Id: <8B4BD695-682A-44CF-BA75-E548F33B2E3F@hibnet.org>
archived-at: Wed, 31 May 2017 15:32:51 -0000

--Apple-Mail=_2B944D52-60BF-4E85-8E16-1ACBB7AD2747
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=utf-8


> Le 31 mai 2017 =C3=A0 15:34, J Pai <jai.forums2013@gmail.com> a =C3=A9cr=
it :
>=20
> One thing I just noticed in the generated adoc files is that =
=E2=80=9Cexternal=E2=80=9D 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 =E2=80=9CApache =
License=E2=80=9D in this sentence:
>=20
>> Ivy is open source and released under a very permissive Apache =
License.
>>=20
>=20
>=20
> and the =E2=80=9Cfeatures=E2=80=9D in :
>=20
>> Ivy has a lot of powerful features
>=20
> are actually link references in the original xooki backed docs of the =
form [[license Apache License]] and [[features]].

It seems that xooki doesn=E2=80=99t 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

>=20
> -Jaikiran
>=20
> On 31-May-2017, at 6:50 PM, J Pai <jai.forums2013@gmail.com> wrote:
>=20
> 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.
>=20
> There are certain warning about the heading/section level we use in =
the generated adoc files, for top level heading:
>=20
>> [asciidoctor:convert] asciidoctor: WARNING: dependency.adoc: line 7: =
section title out of sequence: expected level 1, got level 2
>=20
>=20
> but that=E2=80=99s pretty much it in terms of build time =
warnings/errors.
>=20
> 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=E2=80=99t aware that Nicolas had already done =
the bulk of this job by implementing this tool.=20
>=20
> 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=E2=80=99t =
breaking anything, I don=E2=80=99t think we will have to maintain a =
separate branch to deal with this migration.
>=20
> Any thoughts?
>=20
> -Jaikiran
>=20
> On 25-May-2017, at 7:55 PM, Nicolas Lalev=C3=A9e =
<nicolas.lalevee@hibnet.org> wrote:
>=20
>=20
>> Le 25 mai 2017 =C3=A0 16:17, Matt Sicker <boards@gmail.com> a =C3=A9cri=
t :
>>=20
>> Merge commits always spam the commits list which, while annoying, =
I've
>> learned to mass-delete whenever it happens. ;)
>>=20
>> I looked at some random changes and found a couple markup typos, but
>> otherwise it looks like it converted well enough.
>=20
> Yes, I have stopped one too. Some things will need to be manually =
fixed after the automatic conversion.
>=20
>> 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?
>=20
> 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.
>=20
> But we can imagine that we uncouple the documentation, like it is =
being done for the old versions of the documentation, in the =C2=AB =
history =C2=BB section, by just having a link. So yes we could some =
manual copy and publish to svnpubsub on release.
>=20
> Nicolas
>=20
>>=20
>> On 25 May 2017 at 09:00, Nicolas Lalev=C3=A9e =
<nicolas.lalevee@hibnet.org> wrote:
>>=20
>>> 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.
>>>=20
>>> 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>
>>>=20
>>> It seems pretty good, but I didn=E2=80=99t looked to most of the =
pages.
>>>=20
>>> 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.
>>>=20
>>> Nicolas
>>>=20
>>>=20
>>=20
>>=20
>> --=20
>> Matt Sicker <boards@gmail.com>
>=20
>=20
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
> For additional commands, e-mail: dev-help@ant.apache.org
>=20
>=20
>=20
>=20
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
> For additional commands, e-mail: dev-help@ant.apache.org
>=20


--Apple-Mail=_2B944D52-60BF-4E85-8E16-1ACBB7AD2747--