Ivy documentation with asciidoc

classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Ivy documentation with asciidoc

Nicolas Lalevée
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

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

Matt Sicker
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.

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?

On 25 May 2017 at 09:00, Nicolas Lalevée <[hidden email]> 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 <[hidden email]>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

Nicolas Lalevée

> Le 25 mai 2017 à 16:17, Matt Sicker <[hidden email]> 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 <[hidden email]> 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 <[hidden email]>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

J Pai
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 <[hidden email]> wrote:


> Le 25 mai 2017 à 16:17, Matt Sicker <[hidden email]> 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 <[hidden email]> 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 <[hidden email]>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]



---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

J Pai
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]].

-Jaikiran

On 31-May-2017, at 6:50 PM, J Pai <[hidden email]> 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 <[hidden email]> wrote:


> Le 25 mai 2017 à 16:17, Matt Sicker <[hidden email]> 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 <[hidden email]> 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 <[hidden email]>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]




---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

Gintautas Grigelionis
In reply to this post by J Pai
Great news! How about SVG for images? I thought about tracing the Ivy logo;
also, dependency graphs made with yEd can be saved in SVG. What about using
fonts (eg genericons) instead of images for arrows etc?

Gintas

2017-05-31 15:20 GMT+02:00 J Pai <[hidden email]>:

> 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 <[hidden email]>
> wrote:
>
>
> > Le 25 mai 2017 à 16:17, Matt Sicker <[hidden email]> 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 <[hidden email]>
> 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 <[hidden email]>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

Nicolas Lalevée
In reply to this post by J Pai

> Le 31 mai 2017 à 15:20, J Pai <[hidden email]> a écrit :
>
> 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.

The goal of this tool is not to generate completely asciidoc compatible source, just do most of the stuff automatically. For instance, fixing the issue with the title level automatically will be hard I think, at least harder than fixing it manually afterward.
So the question about it being ready or not, is more about if we are ready to fix manually what is not being correctly converted.

About keeping the old xooki sources: I don’t think this will be necessary, we have git for that. But probably just before migrating, we could generate the doc one last time with xooki and keep it somewhere so we can compare the final result while fixing manually the asciidoc sources.

Then about when to do it: I have no objection to when, as long as people are motivated to do it.

Nicolas


> Any thoughts?
>
> -Jaikiran
>
> On 25-May-2017, at 7:55 PM, Nicolas Lalevée <[hidden email]> wrote:
>
>
>> Le 25 mai 2017 à 16:17, Matt Sicker <[hidden email]> 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 <[hidden email]> 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 <[hidden email]>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

Nicolas Lalevée
In reply to this post by J Pai

> Le 31 mai 2017 à 15:34, J Pai <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> wrote:
>
>
>> Le 25 mai 2017 à 16:17, Matt Sicker <[hidden email]> 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 <[hidden email]> 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 <[hidden email]>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

J Pai

On 31-May-2017, at 9:02 PM, Nicolas Lalevée <[hidden email]> wrote:


> Le 31 mai 2017 à 15:34, J Pai <[hidden email]> 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.


I suspect it has to do with how/where those HTMLs got generated. Because in the latest-milestone live ones, I see them as links on this page https://ant.apache.org/ivy/history/latest-milestone/index.html


-Jaikiran
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

Nicolas Lalevée

> Le 31 mai 2017 à 17:53, J Pai <[hidden email]> a écrit :
>
>
> On 31-May-2017, at 9:02 PM, Nicolas Lalevée <[hidden email] <mailto:[hidden email]>> wrote:
>
>
>> Le 31 mai 2017 à 15:34, J Pai <[hidden email]> 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> <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.
>
>
> I suspect it has to do with how/where those HTMLs got generated. Because in the latest-milestone live ones, I see them as links on this page https://ant.apache.org/ivy/history/latest-milestone/index.html <https://ant.apache.org/ivy/history/latest-milestone/index.html>

Good catch.
Then the links should be absolute since they are not referencing something within the doc.

Nicolas

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

Gintautas Grigelionis
I looked at the documentation: both
http://ant.apache.org/ivy/history/trunk/tutorial/start.html and
https://ant.apache.org/ivy/history/latest-milestone/tutorial/start.html
have black rectangles.

Also, external links must be pruned and/or directed to Internet Archive :-(
The tutorial of yEd must be revised, version 3 has many more controls. I
converted the odg diagrams to svg, and started looking at Ivy report/yEd
screenshots. The original Ivy logo is unfortunately too low resolution for
simple tracing :-( Is this all there is?

Gintas

2017-05-31 18:20 GMT+02:00 Nicolas Lalevée <[hidden email]>:

>
> > Le 31 mai 2017 à 17:53, J Pai <[hidden email]> a écrit :
> >
> >
> > On 31-May-2017, at 9:02 PM, Nicolas Lalevée <[hidden email]
> <mailto:[hidden email]>> wrote:
> >
> >
> >> Le 31 mai 2017 à 15:34, J Pai <[hidden email]> 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> <
> 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.
> >
> >
> > I suspect it has to do with how/where those HTMLs got generated. Because
> in the latest-milestone live ones, I see them as links on this page
> https://ant.apache.org/ivy/history/latest-milestone/index.html <
> https://ant.apache.org/ivy/history/latest-milestone/index.html>
>
> Good catch.
> Then the links should be absolute since they are not referencing something
> within the doc.
>
> Nicolas
>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

Nicolas Lalevée

> Le 31 mai 2017 à 19:47, Gintautas Grigelionis <[hidden email]> a écrit :
>
> I looked at the documentation: both
> http://ant.apache.org/ivy/history/trunk/tutorial/start.html <http://ant.apache.org/ivy/history/trunk/tutorial/start.html> and
> https://ant.apache.org/ivy/history/latest-milestone/tutorial/start.html <https://ant.apache.org/ivy/history/latest-milestone/tutorial/start.html>
> have black rectangles.

There should be the logs generated automatically there. These logs are generated by the task generate-tutorial-output in the build-release.xml in the sources of Ivy.

I think the way we generate the website is incorrect regarding these logs, because building the site is only about calling xooki, not generate the tutorial logs. Hence the empty black rectangles. This need to be reviewed.
Probably while migrating to asciidoc, we should do like Matt suggested. When releasing, also do a build of the doc, which will include the generation of the logs of the tutorial, and then push manually the doc into the svn of the site.

> Also, external links must be pruned and/or directed to Internet Archive :-(
> The tutorial of yEd must be revised, version 3 has many more controls. I
> converted the odg diagrams to svg, and started looking at Ivy report/yEd
> screenshots. The original Ivy logo is unfortunately too low resolution for
> simple tracing :-( Is this all there is?

The only version of the logo we have is in the svn.

Nicolas

>
> Gintas
>
> 2017-05-31 18:20 GMT+02:00 Nicolas Lalevée <[hidden email] <mailto:[hidden email]>>:
>
>>
>>> Le 31 mai 2017 à 17:53, J Pai <[hidden email] <mailto:[hidden email]>> a écrit :
>>>
>>>
>>> On 31-May-2017, at 9:02 PM, Nicolas Lalevée <[hidden email] <mailto:[hidden email]>
>> <mailto:[hidden email] <mailto:[hidden email]>>> wrote:
>>>
>>>
>>>> Le 31 mai 2017 à 15:34, J Pai <[hidden email]> 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> <
>> http://ant.apache.org/ivy/history/trunk/index.html <http://ant.apache.org/ivy/history/trunk/index.html>> <
>> http://ant.apache.org/ivy/history/trunk/index.html <http://ant.apache.org/ivy/history/trunk/index.html> <
>> 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.
>>>
>>>
>>> I suspect it has to do with how/where those HTMLs got generated. Because
>> in the latest-milestone live ones, I see them as links on this page
>> https://ant.apache.org/ivy/history/latest-milestone/index.html <https://ant.apache.org/ivy/history/latest-milestone/index.html> <
>> https://ant.apache.org/ivy/history/latest-milestone/index.html <https://ant.apache.org/ivy/history/latest-milestone/index.html>>
>>
>> Good catch.
>> Then the links should be absolute since they are not referencing something
>> within the doc.
>>
>> Nicolas

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

Gintautas Grigelionis
2017-05-31 23:00 GMT+02:00 Nicolas Lalevée <[hidden email]>:

>
> > Le 31 mai 2017 à 19:47, Gintautas Grigelionis <[hidden email]>
> a écrit :
> >

> Also, external links must be pruned and/or directed to Internet Archive
> :-(
> > The tutorial of yEd must be revised, version 3 has many more controls. I
> > converted the odg diagrams to svg, and started looking at Ivy report/yEd
> > screenshots. The original Ivy logo is unfortunately too low resolution
> for
> > simple tracing :-( Is this all there is?
>
> The only version of the logo we have is in the svn.
>

That's a pity.

A couple of related questions: Apache Incubator has changed the logo,
should the new logo from their press release kit be used in documentation
instead? Next, there is an "Apache Ant Group" logo that looks like the
regular ASF feather <https://commons.wikimedia.org/wiki/File:ASF-logo.svg>
mirrored horisontally with the text on top of it. Is that an official logo?

Gintas
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

Stefan Bodewig
On 2017-06-01, Gintautas Grigelionis wrote:

> 2017-05-31 23:00 GMT+02:00 Nicolas Lalevée <[hidden email]>:


>>> Le 31 mai 2017 à 19:47, Gintautas Grigelionis <[hidden email]>
>> a écrit :


>> Also, external links must be pruned and/or directed to Internet Archive
>>> -(
>>> The tutorial of yEd must be revised, version 3 has many more controls. I
>>> converted the odg diagrams to svg, and started looking at Ivy report/yEd
>>> screenshots. The original Ivy logo is unfortunately too low resolution
>> for
>>> simple tracing :-( Is this all there is?

>> The only version of the logo we have is in the svn.


> That's a pity.

> A couple of related questions: Apache Incubator has changed the logo,
> should the new logo from their press release kit be used in documentation
> instead?

Does the Ivy doc include the Incubator logo anywhere? If so, we may want
to update it. But it can surely only be in a historical context, so
keeping the old logo would probably be fine.

> Next, there is an "Apache Ant Group" logo that looks like the regular
> ASF feather <https://commons.wikimedia.org/wiki/File:ASF-logo.svg>
> mirrored horisontally with the text on top of it. Is that an official
> logo?

It is. We know the ASF logo has changed in the mean time and yes, in a
way we are expected to adjust to the new logo. Nobody is going to do
that for us, each project is responsible for their own stuff.

Stefan

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ivy documentation with asciidoc

Gintautas Grigelionis
2017-06-01 15:43 GMT+02:00 Stefan Bodewig <[hidden email]>:

> On 2017-06-01, Gintautas Grigelionis wrote:
>
> > 2017-05-31 23:00 GMT+02:00 Nicolas Lalevée <[hidden email]>:
>
>
> >>> Le 31 mai 2017 à 19:47, Gintautas Grigelionis <[hidden email]
> >
> >> a écrit :
>
>
> >> Also, external links must be pruned and/or directed to Internet Archive
> >>> -(
> >>> The tutorial of yEd must be revised, version 3 has many more controls.
> I
> >>> converted the odg diagrams to svg, and started looking at Ivy
> report/yEd
> >>> screenshots. The original Ivy logo is unfortunately too low resolution
> >> for
> >>> simple tracing :-( Is this all there is?
>
> >> The only version of the logo we have is in the svn.
>
>
> > That's a pity.
>
> > A couple of related questions: Apache Incubator has changed the logo,
> > should the new logo from their press release kit be used in documentation
> > instead?
>
> Does the Ivy doc include the Incubator logo anywhere? If so, we may want
> to update it. But it can surely only be in a historical context, so
> keeping the old logo would probably be fine.


If there are no guidelines, fine. But ASF seems to have put quite an effort
in a press release kit...


> > Next, there is an "Apache Ant Group" logo that looks like the regular
> > ASF feather <https://commons.wikimedia.org/wiki/File:ASF-logo.svg>
> > mirrored horisontally with the text on top of it. Is that an official
> > logo?
>
> It is. We know the ASF logo has changed in the mean time and yes, in a
> way we are expected to adjust to the new logo. Nobody is going to do
> that for us, each project is responsible for their own stuff.


If that's fine with the project (group :-), I'll try to make an SVG version
of the logo.

Gintas
Loading...