Ivy - we have now moved to asciidoc for docs

classic Classic list List threaded Threaded
26 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Ivy - we have now moved to asciidoc for docs

Jaikiran Pai
The documentation for ant-ivy project has now been migrated to asciidoc. The migration used a tool developed by Nicolas to migrate the xooki backed HTML docs to asciidoc. This tool auto-generated the asciidoc text and for most part no other changes were needed. However, there are some fixes the generated asciidoc will need which I’m doing and will continue to do in the coming days to fix any issues with the generated doc. Once the fixes are done, soon, we’ll remove the xooki backed documentation completely from our git repo. For now though, any new documentation or changes should go into the asciidoc files.

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

Reply | Threaded
Open this post in threaded view
|

AW: Ivy - we have now moved to asciidoc for docs

Jan Matèrne (jhm)
Doc's mentioning 'how to document' must be updated.
I found http://ant.apache.org/ivy/write-doc.html Some more?

Jan

> -----Ursprüngliche Nachricht-----
> Von: Jaikiran Pai [mailto:[hidden email]]
> Gesendet: Montag, 19. Juni 2017 04:52
> An: Ant Developers List
> Betreff: Ivy - we have now moved to asciidoc for docs
>
> The documentation for ant-ivy project has now been migrated to
> asciidoc. The migration used a tool developed by Nicolas to migrate the
> xooki backed HTML docs to asciidoc. This tool auto-generated the
> asciidoc text and for most part no other changes were needed. However,
> there are some fixes the generated asciidoc will need which I’m doing
> and will continue to do in the coming days to fix any issues with the
> generated doc. Once the fixes are done, soon, we’ll remove the xooki
> backed documentation completely from our git repo. For now though, any
> new documentation or changes should go into the asciidoc files.
>
> -Jaikiran
> ---------------------------------------------------------------------
> 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
|

Re: Ivy - we have now moved to asciidoc for docs

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

> Le 19 juin 2017 à 04:52, Jaikiran Pai <[hidden email]> a écrit :
>
> The documentation for ant-ivy project has now been migrated to asciidoc. The migration used a tool developed by Nicolas to migrate the xooki backed HTML docs to asciidoc. This tool auto-generated the asciidoc text and for most part no other changes were needed. However, there are some fixes the generated asciidoc will need which I’m doing and will continue to do in the coming days to fix any issues with the generated doc. Once the fixes are done, soon, we’ll remove the xooki backed documentation completely from our git repo. For now though, any new documentation or changes should go into the asciidoc files.

I did a general grep about finding non translated html markup, and I have cleaned the ones I have found.
I have pushed the result here: http://people.apache.org/~hibou/doc/ <http://people.apache.org/~hibou/doc/>

Probably we can start pushing it to the site, since there is section dedicated to the trunk version of the doc (which should be probably renamed master).
http://ant.apache.org/ivy/history/trunk/index.html <http://ant.apache.org/ivy/history/trunk/index.html>
It would be an opportunity to get an idea of what would it mean when a release will happen.

I have noticed one bug in the generation of the toc. There is notion of abstract node, which has a title but no link, it shouldn’t be clickable. But for instance the node at Reference/Introduction is clickable, and sends to the home. This should be fixed. I mentioning it if somebody wants to look at it, before me.

And just an idea: since there are a lot of pages, maybe we could organize a review at many, without useless double checks. I see 4 big parts in the doc: the ant tasks, the pages related to the ivy file, the pages related to the ivysettings, and the other pages. If 4 volunteers can do a quick review of each page, I think we can be pretty confident that we didn’t leave any ugliness somewhere. The goal wouldn’t to do a fine grain review, but ensure that everything is readable. wdyt ?

Nicolas

Reply | Threaded
Open this post in threaded view
|

Re: Ivy - we have now moved to asciidoc for docs

Nicolas Lalevée
In reply to this post by Jan Matèrne (jhm)

> Le 19 juin 2017 à 08:30, Jan Matèrne (jhm) <[hidden email]> a écrit :
>
> Doc's mentioning 'how to document' must be updated.
> I found http://ant.apache.org/ivy/write-doc.html Some more?

This is the only page which explain xooki I know.

Nicolas

>
> Jan
>
>> -----Ursprüngliche Nachricht-----
>> Von: Jaikiran Pai [mailto:[hidden email]]
>> Gesendet: Montag, 19. Juni 2017 04:52
>> An: Ant Developers List
>> Betreff: Ivy - we have now moved to asciidoc for docs
>>
>> The documentation for ant-ivy project has now been migrated to
>> asciidoc. The migration used a tool developed by Nicolas to migrate the
>> xooki backed HTML docs to asciidoc. This tool auto-generated the
>> asciidoc text and for most part no other changes were needed. However,
>> there are some fixes the generated asciidoc will need which I’m doing
>> and will continue to do in the coming days to fix any issues with the
>> generated doc. Once the fixes are done, soon, we’ll remove the xooki
>> backed documentation completely from our git repo. For now though, any
>> new documentation or changes should go into the asciidoc files.
>>
>> -Jaikiran
>> ---------------------------------------------------------------------
>> 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
|

Re: Ivy - we have now moved to asciidoc for docs

Gintautas Grigelionis
SVG is inlined as code, see http://people.apache.org/~hibou/doc/osgi.html

Gintas

2017-06-20 0:09 GMT+02:00 Nicolas Lalevée <[hidden email]>:

>
> > Le 19 juin 2017 à 08:30, Jan Matèrne (jhm) <[hidden email]> a écrit :
> >
> > Doc's mentioning 'how to document' must be updated.
> > I found http://ant.apache.org/ivy/write-doc.html Some more?
>
> This is the only page which explain xooki I know.
>
> Nicolas
>
> >
> > Jan
> >
> >> -----Ursprüngliche Nachricht-----
> >> Von: Jaikiran Pai [mailto:[hidden email]]
> >> Gesendet: Montag, 19. Juni 2017 04:52
> >> An: Ant Developers List
> >> Betreff: Ivy - we have now moved to asciidoc for docs
> >>
> >> The documentation for ant-ivy project has now been migrated to
> >> asciidoc. The migration used a tool developed by Nicolas to migrate the
> >> xooki backed HTML docs to asciidoc. This tool auto-generated the
> >> asciidoc text and for most part no other changes were needed. However,
> >> there are some fixes the generated asciidoc will need which I’m doing
> >> and will continue to do in the coming days to fix any issues with the
> >> generated doc. Once the fixes are done, soon, we’ll remove the xooki
> >> backed documentation completely from our git repo. For now though, any
> >> new documentation or changes should go into the asciidoc files.
> >>
> >> -Jaikiran
> >> ---------------------------------------------------------------------
> >> 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
|

Re: Ivy - we have now moved to asciidoc for docs

Jaikiran Pai
In reply to this post by Nicolas Lalevée
Yes, that appears to be the only place where we explain documentation contribution.

However, the IvyDE project page too points to this page. That’s a reminder for us that the IvyDE project too probably needs to move to asciidoc.

-Jaikiran

On 20-Jun-2017, at 3:39 AM, Nicolas Lalevée <[hidden email]> wrote:


> Le 19 juin 2017 à 08:30, Jan Matèrne (jhm) <[hidden email]> a écrit :
>
> Doc's mentioning 'how to document' must be updated.
> I found http://ant.apache.org/ivy/write-doc.html Some more?

This is the only page which explain xooki I know.

Nicolas

>
> Jan
>
>> -----Ursprüngliche Nachricht-----
>> Von: Jaikiran Pai [mailto:[hidden email]]
>> Gesendet: Montag, 19. Juni 2017 04:52
>> An: Ant Developers List
>> Betreff: Ivy - we have now moved to asciidoc for docs
>>
>> The documentation for ant-ivy project has now been migrated to
>> asciidoc. The migration used a tool developed by Nicolas to migrate the
>> xooki backed HTML docs to asciidoc. This tool auto-generated the
>> asciidoc text and for most part no other changes were needed. However,
>> there are some fixes the generated asciidoc will need which I’m doing
>> and will continue to do in the coming days to fix any issues with the
>> generated doc. Once the fixes are done, soon, we’ll remove the xooki
>> backed documentation completely from our git repo. For now though, any
>> new documentation or changes should go into the asciidoc files.
>>
>> -Jaikiran
>> ---------------------------------------------------------------------
>> 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]



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

Reply | Threaded
Open this post in threaded view
|

Re: Ivy - we have now moved to asciidoc for docs

Jaikiran Pai
In reply to this post by Nicolas Lalevée
>
> On 20-Jun-2017, at 3:38 AM, Nicolas Lalevée <[hidden email]> wrote:
>
>
>> Le 19 juin 2017 à 04:52, Jaikiran Pai <[hidden email]> a écrit :
>>
>> The documentation for ant-ivy project has now been migrated to asciidoc. The migration used a tool developed by Nicolas to migrate the xooki backed HTML docs to asciidoc. This tool auto-generated the asciidoc text and for most part no other changes were needed. However, there are some fixes the generated asciidoc will need which I’m doing and will continue to do in the coming days to fix any issues with the generated doc. Once the fixes are done, soon, we’ll remove the xooki backed documentation completely from our git repo. For now though, any new documentation or changes should go into the asciidoc files.
>
> I did a general grep about finding non translated html markup, and I have cleaned the ones I have found.
> I have pushed the result here: http://people.apache.org/~hibou/doc/ <http://people.apache.org/~hibou/doc/>
>
> Probably we can start pushing it to the site, since there is section dedicated to the trunk version of the doc (which should be probably renamed master).
> http://ant.apache.org/ivy/history/trunk/index.html <http://ant.apache.org/ivy/history/trunk/index.html>
> It would be an opportunity to get an idea of what would it mean when a release will happen.

I actually forgot to send a mail yesterday, but I setup our nightly Ivy job on Jenkins to publish the latest generated docs as build artifact so that it gives everyone a chance to view/review it. It’s here https://builds.apache.org/view/A/view/Ant/job/Ivy-NightlyDistribution/lastSuccessfulBuild/artifact/build/. We could just push it to the site under master but I wasn’t too sure if it’s the right time to do that or if we should just cleanup the rest of the issues in the doc before starting to push it there.

>
> And just an idea: since there are a lot of pages, maybe we could organize a review at many, without useless double checks. I see 4 big parts in the doc: the ant tasks, the pages related to the ivy file, the pages related to the ivysettings, and the other pages. If 4 volunteers can do a quick review of each page, I think we can be pretty confident that we didn’t leave any ugliness somewhere. The goal wouldn’t to do a fine grain review, but ensure that everything is readable. wdyt ?
>

Sounds a good idea. I’ll start off with the “Settings” which relates to the Ivy settings file.

-Jaikiran



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

Reply | Threaded
Open this post in threaded view
|

Re: Ivy - we have now moved to asciidoc for docs

Gintautas Grigelionis
I'd happy to help later tonight, please let me know if there's some
particular section that I should look into.
Skimming through quickly, More Examples (
http://people.apache.org/~hibou/doc/moreexamples.html) should be adjusted.

Gintas

2017-06-20 4:16 GMT+02:00 Jaikiran Pai <[hidden email]>:

> >
> > On 20-Jun-2017, at 3:38 AM, Nicolas Lalevée <[hidden email]>
> wrote:
> >
> >
> >> Le 19 juin 2017 à 04:52, Jaikiran Pai <[hidden email]> a
> écrit :
> >>
> >> The documentation for ant-ivy project has now been migrated to
> asciidoc. The migration used a tool developed by Nicolas to migrate the
> xooki backed HTML docs to asciidoc. This tool auto-generated the asciidoc
> text and for most part no other changes were needed. However, there are
> some fixes the generated asciidoc will need which I’m doing and will
> continue to do in the coming days to fix any issues with the generated doc.
> Once the fixes are done, soon, we’ll remove the xooki backed documentation
> completely from our git repo. For now though, any new documentation or
> changes should go into the asciidoc files.
> >
> > I did a general grep about finding non translated html markup, and I
> have cleaned the ones I have found.
> > I have pushed the result here: http://people.apache.org/~hibou/doc/ <
> http://people.apache.org/~hibou/doc/>
> >
> > Probably we can start pushing it to the site, since there is section
> dedicated to the trunk version of the doc (which should be probably renamed
> master).
> > http://ant.apache.org/ivy/history/trunk/index.html <
> http://ant.apache.org/ivy/history/trunk/index.html>
> > It would be an opportunity to get an idea of what would it mean when a
> release will happen.
>
> I actually forgot to send a mail yesterday, but I setup our nightly Ivy
> job on Jenkins to publish the latest generated docs as build artifact so
> that it gives everyone a chance to view/review it. It’s here
> https://builds.apache.org/view/A/view/Ant/job/Ivy-NightlyDistribution/
> lastSuccessfulBuild/artifact/build/. We could just push it to the site
> under master but I wasn’t too sure if it’s the right time to do that or if
> we should just cleanup the rest of the issues in the doc before starting to
> push it there.
>
> >
> > And just an idea: since there are a lot of pages, maybe we could
> organize a review at many, without useless double checks. I see 4 big parts
> in the doc: the ant tasks, the pages related to the ivy file, the pages
> related to the ivysettings, and the other pages. If 4 volunteers can do a
> quick review of each page, I think we can be pretty confident that we
> didn’t leave any ugliness somewhere. The goal wouldn’t to do a fine grain
> review, but ensure that everything is readable. wdyt ?
> >
>
> Sounds a good idea. I’ll start off with the “Settings” which relates to
> the Ivy settings file.
>
> -Jaikiran
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Ivy - we have now moved to asciidoc for docs

Nicolas Lalevée
In reply to this post by Jaikiran Pai
>
>>
>> And just an idea: since there are a lot of pages, maybe we could organize a review at many, without useless double checks. I see 4 big parts in the doc: the ant tasks, the pages related to the ivy file, the pages related to the ivysettings, and the other pages. If 4 volunteers can do a quick review of each page, I think we can be pretty confident that we didn’t leave any ugliness somewhere. The goal wouldn’t to do a fine grain review, but ensure that everything is readable. wdyt ?
>>
>
> Sounds a good idea. I’ll start off with the “Settings” which relates to the Ivy settings file.

Great. I’ll take care of « Ivy Files ».

Nicolas


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

Reply | Threaded
Open this post in threaded view
|

Re: Ivy - we have now moved to asciidoc for docs

Jaikiran Pai
A quick update on this one - I finished off the “settings” sections last week. There is only one pending item that I’m trying to address in that section. The “Settings” page[1] has a “Settings File Structure” section which tries to represent the Ivy settings XML file structure as a tree. We have a similar one, one place else too (in Ivy file page). We use a source code block to represent it. However, Asciidoc source code blocks are rendered literally, so it won’t show up the links (as you’ll see in that page[1] currently). For the Ivy page, I used “lists” to render the structure and that was “good enough"[2]. However, I can’t use the same here since Asciidoc (backed by asciidoctor generator) allows a max list depth of 5 which means that any nested elements that exceed that depth won’t be rendered correctly as a tree. The settings file structure goes beyond that depth limit so it doesn’t work out well here.

Ultimately, we either have to remove that section (there’s already a “Child elements” section which _almost_ conveys the same thing) or come up with a custom asciidoc “tree” kind of block element to render this. Any thoughts?

By the way, I consider the settings section to be “done” in terms of migration. If anyone however notices any discrepancies while doing a quick review of the rendered pages, feel free to drop a mail.

I’m picking up “OSGi” section next.

[1] https://builds.apache.org/view/A/view/Ant/job/Ivy-NightlyDistribution/lastSuccessfulBuild/artifact/build/doc/settings.html
[2] See “Hierarchical Index” section at https://builds.apache.org/view/A/view/Ant/job/Ivy-NightlyDistribution/lastSuccessfulBuild/artifact/build/doc/ivyfile.html

-Jaikiran

On 24-Jun-2017, at 7:18 PM, Nicolas Lalevée <[hidden email]> wrote:

>
>>
>> And just an idea: since there are a lot of pages, maybe we could organize a review at many, without useless double checks. I see 4 big parts in the doc: the ant tasks, the pages related to the ivy file, the pages related to the ivysettings, and the other pages. If 4 volunteers can do a quick review of each page, I think we can be pretty confident that we didn’t leave any ugliness somewhere. The goal wouldn’t to do a fine grain review, but ensure that everything is readable. wdyt ?
>>
>
> Sounds a good idea. I’ll start off with the “Settings” which relates to the Ivy settings file.

Great. I’ll take care of « Ivy Files ».

Nicolas


---------------------------------------------------------------------
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
|

Re: Ivy - we have now moved to asciidoc for docs

Nicolas Lalevée

> Le 29 juin 2017 à 07:59, Jaikiran Pai <[hidden email]> a écrit :
>
> A quick update on this one - I finished off the “settings” sections last week. There is only one pending item that I’m trying to address in that section. The “Settings” page[1] has a “Settings File Structure” section which tries to represent the Ivy settings XML file structure as a tree. We have a similar one, one place else too (in Ivy file page). We use a source code block to represent it. However, Asciidoc source code blocks are rendered literally, so it won’t show up the links (as you’ll see in that page[1] currently). For the Ivy page, I used “lists” to render the structure and that was “good enough"[2]. However, I can’t use the same here since Asciidoc (backed by asciidoctor generator) allows a max list depth of 5 which means that any nested elements that exceed that depth won’t be rendered correctly as a tree. The settings file structure goes beyond that depth limit so it doesn’t work out well here.
>
> Ultimately, we either have to remove that section (there’s already a “Child elements” section which _almost_ conveys the same thing) or come up with a custom asciidoc “tree” kind of block element to render this. Any thoughts?

If I count correctly, there are 6 levels. So could we just remove the root element from the tree so we save one level ? The root would be just printed as some text. Could it then display correctly ?
If it is too weird, let’s remove that section; the tree is shown in the toc so I guess it is OK.

> By the way, I consider the settings section to be “done” in terms of migration. If anyone however notices any discrepancies while doing a quick review of the rendered pages, feel free to drop a mail.
>
> I’m picking up “OSGi” section next.

And I have done the Ivy files, I’ll review the Ant Tasks section now.

Nicolas

>
> [1] https://builds.apache.org/view/A/view/Ant/job/Ivy-NightlyDistribution/lastSuccessfulBuild/artifact/build/doc/settings.html
> [2] See “Hierarchical Index” section at https://builds.apache.org/view/A/view/Ant/job/Ivy-NightlyDistribution/lastSuccessfulBuild/artifact/build/doc/ivyfile.html
>
> -Jaikiran
>
> On 24-Jun-2017, at 7:18 PM, Nicolas Lalevée <[hidden email]> wrote:
>
>>
>>>
>>> And just an idea: since there are a lot of pages, maybe we could organize a review at many, without useless double checks. I see 4 big parts in the doc: the ant tasks, the pages related to the ivy file, the pages related to the ivysettings, and the other pages. If 4 volunteers can do a quick review of each page, I think we can be pretty confident that we didn’t leave any ugliness somewhere. The goal wouldn’t to do a fine grain review, but ensure that everything is readable. wdyt ?
>>>
>>
>> Sounds a good idea. I’ll start off with the “Settings” which relates to the Ivy settings file.
>
> Great. I’ll take care of « Ivy Files ».
>
> Nicolas
>
>
> ---------------------------------------------------------------------
> 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
|

Re: Ivy - we have now moved to asciidoc for docs

Jaikiran Pai

On 29-Jun-2017, at 3:58 PM, Nicolas Lalevée <[hidden email]> wrote:

>
>> Le 29 juin 2017 à 07:59, Jaikiran Pai <[hidden email]> a écrit :
>>
>> A quick update on this one - I finished off the “settings” sections last week. There is only one pending item that I’m trying to address in that section. The “Settings” page[1] has a “Settings File Structure” section which tries to represent the Ivy settings XML file structure as a tree. We have a similar one, one place else too (in Ivy file page). We use a source code block to represent it. However, Asciidoc source code blocks are rendered literally, so it won’t show up the links (as you’ll see in that page[1] currently). For the Ivy page, I used “lists” to render the structure and that was “good enough"[2]. However, I can’t use the same here since Asciidoc (backed by asciidoctor generator) allows a max list depth of 5 which means that any nested elements that exceed that depth won’t be rendered correctly as a tree. The settings file structure goes beyond that depth limit so it doesn’t work out well here.
>>
>> Ultimately, we either have to remove that section (there’s already a “Child elements” section which _almost_ conveys the same thing) or come up with a custom asciidoc “tree” kind of block element to render this. Any thoughts?
>
> If I count correctly, there are 6 levels. So could we just remove the root element from the tree so we save one level ? The root would be just printed as some text. Could it then display correctly ?
>

That suggestion actually worked well. I went ahead and did that change and regenerated the latest “master” site. It looks good http://ant.apache.org/ivy/history/master/settings.html.

-Jaikiran



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

Reply | Threaded
Open this post in threaded view
|

Re: Ivy - we have now moved to asciidoc for docs

Nicolas Lalevée
I have seen that you have qualified the source blocks, telling it is xml. Then I have done the same for the 'Ivy File' and 'Ant Tasks’ sections. And I enabled the highlightjs integration with acsiidoctor. I don’t find the default theme that cute (too lazy to search another one), but it is nicer than nothing :)
I also seen some extended use of ‘code’ formatting, using ` in the asciidoc files. So I have done as well on the sections I have worked on. And I have put a little gray background color to improve the result. I hope it is not too invasive.

You can see the result on the site.

Probably a thing to improve are all the « since 2.x » annotations. Maybe we can have a macro for that, which will render everywhere the same, and which will be placed everywhere the same. Now sometimes it is at the beginning of the line, sometimes at the end, sometimes above. And I find it being black bold a little too much.

Nicolas

> Le 29 juin 2017 à 15:16, Jaikiran Pai <[hidden email]> a écrit :
>
>
> On 29-Jun-2017, at 3:58 PM, Nicolas Lalevée <[hidden email]> wrote:
>
>>
>>> Le 29 juin 2017 à 07:59, Jaikiran Pai <[hidden email]> a écrit :
>>>
>>> A quick update on this one - I finished off the “settings” sections last week. There is only one pending item that I’m trying to address in that section. The “Settings” page[1] has a “Settings File Structure” section which tries to represent the Ivy settings XML file structure as a tree. We have a similar one, one place else too (in Ivy file page). We use a source code block to represent it. However, Asciidoc source code blocks are rendered literally, so it won’t show up the links (as you’ll see in that page[1] currently). For the Ivy page, I used “lists” to render the structure and that was “good enough"[2]. However, I can’t use the same here since Asciidoc (backed by asciidoctor generator) allows a max list depth of 5 which means that any nested elements that exceed that depth won’t be rendered correctly as a tree. The settings file structure goes beyond that depth limit so it doesn’t work out well here.
>>>
>>> Ultimately, we either have to remove that section (there’s already a “Child elements” section which _almost_ conveys the same thing) or come up with a custom asciidoc “tree” kind of block element to render this. Any thoughts?
>>
>> If I count correctly, there are 6 levels. So could we just remove the root element from the tree so we save one level ? The root would be just printed as some text. Could it then display correctly ?
>>
>
> That suggestion actually worked well. I went ahead and did that change and regenerated the latest “master” site. It looks good http://ant.apache.org/ivy/history/master/settings.html.
>
> -Jaikiran
>
>
>
> ---------------------------------------------------------------------
> 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
|

Re: Ivy - we have now moved to asciidoc for docs

Gintautas Grigelionis
terminology.adoc apparently has an incorrect link on line 150,
configuration/statuses.html should be settings/statuses.html
(I get a redirect from
http://ant.apache.org/ivy/history/master/terminology.html)

Gintas

2017-06-30 18:18 GMT+02:00 Nicolas Lalevée <[hidden email]>:

> I have seen that you have qualified the source blocks, telling it is xml.
> Then I have done the same for the 'Ivy File' and 'Ant Tasks’ sections. And
> I enabled the highlightjs integration with acsiidoctor. I don’t find the
> default theme that cute (too lazy to search another one), but it is nicer
> than nothing :)
> I also seen some extended use of ‘code’ formatting, using ` in the
> asciidoc files. So I have done as well on the sections I have worked on.
> And I have put a little gray background color to improve the result. I hope
> it is not too invasive.
>
> You can see the result on the site.
>
> Probably a thing to improve are all the « since 2.x » annotations. Maybe
> we can have a macro for that, which will render everywhere the same, and
> which will be placed everywhere the same. Now sometimes it is at the
> beginning of the line, sometimes at the end, sometimes above. And I find it
> being black bold a little too much.
>
> Nicolas
>
> > Le 29 juin 2017 à 15:16, Jaikiran Pai <[hidden email]> a
> écrit :
> >
> >
> > On 29-Jun-2017, at 3:58 PM, Nicolas Lalevée <[hidden email]>
> wrote:
> >
> >>
> >>> Le 29 juin 2017 à 07:59, Jaikiran Pai <[hidden email]> a
> écrit :
> >>>
> >>> A quick update on this one - I finished off the “settings” sections
> last week. There is only one pending item that I’m trying to address in
> that section. The “Settings” page[1] has a “Settings File Structure”
> section which tries to represent the Ivy settings XML file structure as a
> tree. We have a similar one, one place else too (in Ivy file page). We use
> a source code block to represent it. However, Asciidoc source code blocks
> are rendered literally, so it won’t show up the links (as you’ll see in
> that page[1] currently). For the Ivy page, I used “lists” to render the
> structure and that was “good enough"[2]. However, I can’t use the same here
> since Asciidoc (backed by asciidoctor generator) allows a max list depth of
> 5 which means that any nested elements that exceed that depth won’t be
> rendered correctly as a tree. The settings file structure goes beyond that
> depth limit so it doesn’t work out well here.
> >>>
> >>> Ultimately, we either have to remove that section (there’s already a
> “Child elements” section which _almost_ conveys the same thing) or come up
> with a custom asciidoc “tree” kind of block element to render this. Any
> thoughts?
> >>
> >> If I count correctly, there are 6 levels. So could we just remove the
> root element from the tree so we save one level ? The root would be just
> printed as some text. Could it then display correctly ?
> >>
> >
> > That suggestion actually worked well. I went ahead and did that change
> and regenerated the latest “master” site. It looks good
> http://ant.apache.org/ivy/history/master/settings.html.
> >
> > -Jaikiran
> >
> >
> >
> > ---------------------------------------------------------------------
> > 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
|

Re: Ivy - we have now moved to asciidoc for docs

Gintautas Grigelionis
I opened a PR (well, actually two :-() to fix spelling and links that still
point to configuration.

Gintas

2017-06-30 18:44 GMT+02:00 Gintautas Grigelionis <[hidden email]>:

> terminology.adoc apparently has an incorrect link on line 150,
> configuration/statuses.html should be settings/statuses.html
> (I get a redirect from http://ant.apache.org/ivy/
> history/master/terminology.html)
>
> Gintas
>
> 2017-06-30 18:18 GMT+02:00 Nicolas Lalevée <[hidden email]>:
>
>> I have seen that you have qualified the source blocks, telling it is xml.
>> Then I have done the same for the 'Ivy File' and 'Ant Tasks’ sections. And
>> I enabled the highlightjs integration with acsiidoctor. I don’t find the
>> default theme that cute (too lazy to search another one), but it is nicer
>> than nothing :)
>> I also seen some extended use of ‘code’ formatting, using ` in the
>> asciidoc files. So I have done as well on the sections I have worked on.
>> And I have put a little gray background color to improve the result. I hope
>> it is not too invasive.
>>
>> You can see the result on the site.
>>
>> Probably a thing to improve are all the « since 2.x » annotations. Maybe
>> we can have a macro for that, which will render everywhere the same, and
>> which will be placed everywhere the same. Now sometimes it is at the
>> beginning of the line, sometimes at the end, sometimes above. And I find it
>> being black bold a little too much.
>>
>> Nicolas
>>
>> > Le 29 juin 2017 à 15:16, Jaikiran Pai <[hidden email]> a
>> écrit :
>> >
>> >
>> > On 29-Jun-2017, at 3:58 PM, Nicolas Lalevée <[hidden email]>
>> wrote:
>> >
>> >>
>> >>> Le 29 juin 2017 à 07:59, Jaikiran Pai <[hidden email]> a
>> écrit :
>> >>>
>> >>> A quick update on this one - I finished off the “settings” sections
>> last week. There is only one pending item that I’m trying to address in
>> that section. The “Settings” page[1] has a “Settings File Structure”
>> section which tries to represent the Ivy settings XML file structure as a
>> tree. We have a similar one, one place else too (in Ivy file page). We use
>> a source code block to represent it. However, Asciidoc source code blocks
>> are rendered literally, so it won’t show up the links (as you’ll see in
>> that page[1] currently). For the Ivy page, I used “lists” to render the
>> structure and that was “good enough"[2]. However, I can’t use the same here
>> since Asciidoc (backed by asciidoctor generator) allows a max list depth of
>> 5 which means that any nested elements that exceed that depth won’t be
>> rendered correctly as a tree. The settings file structure goes beyond that
>> depth limit so it doesn’t work out well here.
>> >>>
>> >>> Ultimately, we either have to remove that section (there’s already a
>> “Child elements” section which _almost_ conveys the same thing) or come up
>> with a custom asciidoc “tree” kind of block element to render this. Any
>> thoughts?
>> >>
>> >> If I count correctly, there are 6 levels. So could we just remove the
>> root element from the tree so we save one level ? The root would be just
>> printed as some text. Could it then display correctly ?
>> >>
>> >
>> > That suggestion actually worked well. I went ahead and did that change
>> and regenerated the latest “master” site. It looks good
>> http://ant.apache.org/ivy/history/master/settings.html.
>> >
>> > -Jaikiran
>> >
>> >
>> >
>> > ---------------------------------------------------------------------
>> > 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
|

Re: Ivy - we have now moved to asciidoc for docs

Nicolas Lalevée
Thank you very much Gintas.

These PRs are huge, so they will take a little bit of time to process.

Also, in the PR 49 and 50 I can see a lot of commits [1] [2]. For a cleaner git history, could you rebase and squash them ? I don’t require to have one commit, for instance having the two commits in PR 48 is great. But in these two other PR, it seems a little bit noisy.
And does PR 50 depends on PR 49 ? I can see commits from one included in the other.

I bet these « noisy » commits are due to the conflicts generated by other commits. We can avoid these conflicts, and also avoid the work for you to resolve them: just tell us that you have some large commit incoming, and we will try to not modify much what you are working on.

Cheers,
Nicolas

[1] https://github.com/apache/ant-ivy/pull/49/commits <https://github.com/apache/ant-ivy/pull/49/commits>
[2] https://github.com/apache/ant-ivy/pull/50/commits <https://github.com/apache/ant-ivy/pull/50/commits>

> Le 1 juil. 2017 à 08:07, Gintautas Grigelionis <[hidden email]> a écrit :
>
> I opened a PR (well, actually two :-() to fix spelling and links that still
> point to configuration.
>
> Gintas
>
> 2017-06-30 18:44 GMT+02:00 Gintautas Grigelionis <[hidden email]>:
>
>> terminology.adoc apparently has an incorrect link on line 150,
>> configuration/statuses.html should be settings/statuses.html
>> (I get a redirect from http://ant.apache.org/ivy/
>> history/master/terminology.html)
>>
>> Gintas
>>
>> 2017-06-30 18:18 GMT+02:00 Nicolas Lalevée <[hidden email]>:
>>
>>> I have seen that you have qualified the source blocks, telling it is xml.
>>> Then I have done the same for the 'Ivy File' and 'Ant Tasks’ sections. And
>>> I enabled the highlightjs integration with acsiidoctor. I don’t find the
>>> default theme that cute (too lazy to search another one), but it is nicer
>>> than nothing :)
>>> I also seen some extended use of ‘code’ formatting, using ` in the
>>> asciidoc files. So I have done as well on the sections I have worked on.
>>> And I have put a little gray background color to improve the result. I hope
>>> it is not too invasive.
>>>
>>> You can see the result on the site.
>>>
>>> Probably a thing to improve are all the « since 2.x » annotations. Maybe
>>> we can have a macro for that, which will render everywhere the same, and
>>> which will be placed everywhere the same. Now sometimes it is at the
>>> beginning of the line, sometimes at the end, sometimes above. And I find it
>>> being black bold a little too much.
>>>
>>> Nicolas
>>>
>>>> Le 29 juin 2017 à 15:16, Jaikiran Pai <[hidden email]> a
>>> écrit :
>>>>
>>>>
>>>> On 29-Jun-2017, at 3:58 PM, Nicolas Lalevée <[hidden email]>
>>> wrote:
>>>>
>>>>>
>>>>>> Le 29 juin 2017 à 07:59, Jaikiran Pai <[hidden email]> a
>>> écrit :
>>>>>>
>>>>>> A quick update on this one - I finished off the “settings” sections
>>> last week. There is only one pending item that I’m trying to address in
>>> that section. The “Settings” page[1] has a “Settings File Structure”
>>> section which tries to represent the Ivy settings XML file structure as a
>>> tree. We have a similar one, one place else too (in Ivy file page). We use
>>> a source code block to represent it. However, Asciidoc source code blocks
>>> are rendered literally, so it won’t show up the links (as you’ll see in
>>> that page[1] currently). For the Ivy page, I used “lists” to render the
>>> structure and that was “good enough"[2]. However, I can’t use the same here
>>> since Asciidoc (backed by asciidoctor generator) allows a max list depth of
>>> 5 which means that any nested elements that exceed that depth won’t be
>>> rendered correctly as a tree. The settings file structure goes beyond that
>>> depth limit so it doesn’t work out well here.
>>>>>>
>>>>>> Ultimately, we either have to remove that section (there’s already a
>>> “Child elements” section which _almost_ conveys the same thing) or come up
>>> with a custom asciidoc “tree” kind of block element to render this. Any
>>> thoughts?
>>>>>
>>>>> If I count correctly, there are 6 levels. So could we just remove the
>>> root element from the tree so we save one level ? The root would be just
>>> printed as some text. Could it then display correctly ?
>>>>>
>>>>
>>>> That suggestion actually worked well. I went ahead and did that change
>>> and regenerated the latest “master” site. It looks good
>>> http://ant.apache.org/ivy/history/master/settings.html.
>>>>
>>>> -Jaikiran
>>>>
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> 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
|

Re: Ivy - we have now moved to asciidoc for docs

Jaikiran Pai
FWIW - I just finished reviewing PR-48 (the generics changes) https://github.com/apache/ant-ivy/pull/48/. Took me around an hour, the changes look fine :) I just have one comment/question about one of the change in that PR (I have to read up the Java spec or find some necessary documentation for it) https://github.com/apache/ant-ivy/pull/48#discussion-diff-125161935R162. Other than that, the PR looks fine to me.

-Jaikiran
On 01-Jul-2017, at 5:37 PM, Nicolas Lalevée <[hidden email]> wrote:

Thank you very much Gintas.

These PRs are huge, so they will take a little bit of time to process.

Also, in the PR 49 and 50 I can see a lot of commits [1] [2]. For a cleaner git history, could you rebase and squash them ? I don’t require to have one commit, for instance having the two commits in PR 48 is great. But in these two other PR, it seems a little bit noisy.
And does PR 50 depends on PR 49 ? I can see commits from one included in the other.

I bet these « noisy » commits are due to the conflicts generated by other commits. We can avoid these conflicts, and also avoid the work for you to resolve them: just tell us that you have some large commit incoming, and we will try to not modify much what you are working on.

Cheers,
Nicolas

[1] https://github.com/apache/ant-ivy/pull/49/commits <https://github.com/apache/ant-ivy/pull/49/commits>
[2] https://github.com/apache/ant-ivy/pull/50/commits <https://github.com/apache/ant-ivy/pull/50/commits>

> Le 1 juil. 2017 à 08:07, Gintautas Grigelionis <[hidden email]> a écrit :
>
> I opened a PR (well, actually two :-() to fix spelling and links that still
> point to configuration.
>
> Gintas
>
> 2017-06-30 18:44 GMT+02:00 Gintautas Grigelionis <[hidden email]>:
>
>> terminology.adoc apparently has an incorrect link on line 150,
>> configuration/statuses.html should be settings/statuses.html
>> (I get a redirect from http://ant.apache.org/ivy/
>> history/master/terminology.html)
>>
>> Gintas
>>
>> 2017-06-30 18:18 GMT+02:00 Nicolas Lalevée <[hidden email]>:
>>
>>> I have seen that you have qualified the source blocks, telling it is xml.
>>> Then I have done the same for the 'Ivy File' and 'Ant Tasks’ sections. And
>>> I enabled the highlightjs integration with acsiidoctor. I don’t find the
>>> default theme that cute (too lazy to search another one), but it is nicer
>>> than nothing :)
>>> I also seen some extended use of ‘code’ formatting, using ` in the
>>> asciidoc files. So I have done as well on the sections I have worked on.
>>> And I have put a little gray background color to improve the result. I hope
>>> it is not too invasive.
>>>
>>> You can see the result on the site.
>>>
>>> Probably a thing to improve are all the « since 2.x » annotations. Maybe
>>> we can have a macro for that, which will render everywhere the same, and
>>> which will be placed everywhere the same. Now sometimes it is at the
>>> beginning of the line, sometimes at the end, sometimes above. And I find it
>>> being black bold a little too much.
>>>
>>> Nicolas
>>>
>>>> Le 29 juin 2017 à 15:16, Jaikiran Pai <[hidden email]> a
>>> écrit :
>>>>
>>>>
>>>> On 29-Jun-2017, at 3:58 PM, Nicolas Lalevée <[hidden email]>
>>> wrote:
>>>>
>>>>>
>>>>>> Le 29 juin 2017 à 07:59, Jaikiran Pai <[hidden email]> a
>>> écrit :
>>>>>>
>>>>>> A quick update on this one - I finished off the “settings” sections
>>> last week. There is only one pending item that I’m trying to address in
>>> that section. The “Settings” page[1] has a “Settings File Structure”
>>> section which tries to represent the Ivy settings XML file structure as a
>>> tree. We have a similar one, one place else too (in Ivy file page). We use
>>> a source code block to represent it. However, Asciidoc source code blocks
>>> are rendered literally, so it won’t show up the links (as you’ll see in
>>> that page[1] currently). For the Ivy page, I used “lists” to render the
>>> structure and that was “good enough"[2]. However, I can’t use the same here
>>> since Asciidoc (backed by asciidoctor generator) allows a max list depth of
>>> 5 which means that any nested elements that exceed that depth won’t be
>>> rendered correctly as a tree. The settings file structure goes beyond that
>>> depth limit so it doesn’t work out well here.
>>>>>>
>>>>>> Ultimately, we either have to remove that section (there’s already a
>>> “Child elements” section which _almost_ conveys the same thing) or come up
>>> with a custom asciidoc “tree” kind of block element to render this. Any
>>> thoughts?
>>>>>
>>>>> If I count correctly, there are 6 levels. So could we just remove the
>>> root element from the tree so we save one level ? The root would be just
>>> printed as some text. Could it then display correctly ?
>>>>>
>>>>
>>>> That suggestion actually worked well. I went ahead and did that change
>>> and regenerated the latest “master” site. It looks good
>>> http://ant.apache.org/ivy/history/master/settings.html.
>>>>
>>>> -Jaikiran
>>>>
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> 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
|

Re: Ivy - we have now moved to asciidoc for docs

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

On 30-Jun-2017, at 9:48 PM, Nicolas Lalevée <[hidden email]> wrote:

> I have seen that you have qualified the source blocks, telling it is xml. Then I have done the same for the 'Ivy File' and 'Ant Tasks’ sections. And I enabled the highlightjs integration with acsiidoctor. I don’t find the default theme that cute (too lazy to search another one), but it is nicer than nothing :)

Thanks! Agreed that the style can be improved, but as you say, it’s better than the bland gray background we had for such blocks earlier.

> I also seen some extended use of ‘code’ formatting, using ` in the asciidoc files. So I have done as well on the sections I have worked on. And I have put a little gray background color to improve the result. I hope it is not too invasive.

I actually find this change an improvement. Earlier, although such text did appear a bit different, it still wasn’t distinguished enough and I sometimes (depending on the browser/font size) had to really focus hard to distinguish it from regular text.

> Probably a thing to improve are all the « since 2.x » annotations. Maybe we can have a macro for that, which will render everywhere the same, and which will be placed everywhere the same. Now sometimes it is at the beginning of the line, sometimes at the end, sometimes above. And I find it being black bold a little too much.

Agreed. Maybe we could do something similar with the “experimental” note/section that we repeat (copy/paste really) on our OSGi pages.

-Jaikiran

> Le 29 juin 2017 à 15:16, Jaikiran Pai <[hidden email]> a écrit :
>
>
> On 29-Jun-2017, at 3:58 PM, Nicolas Lalevée <[hidden email]> wrote:
>
>>
>>> Le 29 juin 2017 à 07:59, Jaikiran Pai <[hidden email]> a écrit :
>>>
>>> A quick update on this one - I finished off the “settings” sections last week. There is only one pending item that I’m trying to address in that section. The “Settings” page[1] has a “Settings File Structure” section which tries to represent the Ivy settings XML file structure as a tree. We have a similar one, one place else too (in Ivy file page). We use a source code block to represent it. However, Asciidoc source code blocks are rendered literally, so it won’t show up the links (as you’ll see in that page[1] currently). For the Ivy page, I used “lists” to render the structure and that was “good enough"[2]. However, I can’t use the same here since Asciidoc (backed by asciidoctor generator) allows a max list depth of 5 which means that any nested elements that exceed that depth won’t be rendered correctly as a tree. The settings file structure goes beyond that depth limit so it doesn’t work out well here.
>>>
>>> Ultimately, we either have to remove that section (there’s already a “Child elements” section which _almost_ conveys the same thing) or come up with a custom asciidoc “tree” kind of block element to render this. Any thoughts?
>>
>> If I count correctly, there are 6 levels. So could we just remove the root element from the tree so we save one level ? The root would be just printed as some text. Could it then display correctly ?
>>
>
> That suggestion actually worked well. I went ahead and did that change and regenerated the latest “master” site. It looks good http://ant.apache.org/ivy/history/master/settings.html.
>
> -Jaikiran
>
>
>
> ---------------------------------------------------------------------
> 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
|

Re: Ivy - we have now moved to asciidoc for docs

Gintautas Grigelionis
In reply to this post by Nicolas Lalevée
Thank you. PR 49 and 50 became one big spaghetti as I tried to catch up
with your work and learn the ropes :-)
Now, 49 is closed and 50 is squashed.

Cheers,
Gintas

2017-07-01 14:07 GMT+02:00 Nicolas Lalevée <[hidden email]>:

> Thank you very much Gintas.
>
> These PRs are huge, so they will take a little bit of time to process.
>
> Also, in the PR 49 and 50 I can see a lot of commits [1] [2]. For a
> cleaner git history, could you rebase and squash them ? I don’t require to
> have one commit, for instance having the two commits in PR 48 is great. But
> in these two other PR, it seems a little bit noisy.
> And does PR 50 depends on PR 49 ? I can see commits from one included in
> the other.
>
> I bet these « noisy » commits are due to the conflicts generated by other
> commits. We can avoid these conflicts, and also avoid the work for you to
> resolve them: just tell us that you have some large commit incoming, and we
> will try to not modify much what you are working on.
>
> Cheers,
> Nicolas
>
> [1] https://github.com/apache/ant-ivy/pull/49/commits <
> https://github.com/apache/ant-ivy/pull/49/commits>
> [2] https://github.com/apache/ant-ivy/pull/50/commits <
> https://github.com/apache/ant-ivy/pull/50/commits>
>
> > Le 1 juil. 2017 à 08:07, Gintautas Grigelionis <[hidden email]>
> a écrit :
> >
> > I opened a PR (well, actually two :-() to fix spelling and links that
> still
> > point to configuration.
> >
> > Gintas
> >
> > 2017-06-30 18:44 GMT+02:00 Gintautas Grigelionis <
> [hidden email]>:
> >
> >> terminology.adoc apparently has an incorrect link on line 150,
> >> configuration/statuses.html should be settings/statuses.html
> >> (I get a redirect from http://ant.apache.org/ivy/
> >> history/master/terminology.html)
> >>
> >> Gintas
> >>
> >> 2017-06-30 18:18 GMT+02:00 Nicolas Lalevée <[hidden email]
> >:
> >>
> >>> I have seen that you have qualified the source blocks, telling it is
> xml.
> >>> Then I have done the same for the 'Ivy File' and 'Ant Tasks’ sections.
> And
> >>> I enabled the highlightjs integration with acsiidoctor. I don’t find
> the
> >>> default theme that cute (too lazy to search another one), but it is
> nicer
> >>> than nothing :)
> >>> I also seen some extended use of ‘code’ formatting, using ` in the
> >>> asciidoc files. So I have done as well on the sections I have worked
> on.
> >>> And I have put a little gray background color to improve the result. I
> hope
> >>> it is not too invasive.
> >>>
> >>> You can see the result on the site.
> >>>
> >>> Probably a thing to improve are all the « since 2.x » annotations.
> Maybe
> >>> we can have a macro for that, which will render everywhere the same,
> and
> >>> which will be placed everywhere the same. Now sometimes it is at the
> >>> beginning of the line, sometimes at the end, sometimes above. And I
> find it
> >>> being black bold a little too much.
> >>>
> >>> Nicolas
> >>>
> >>>> Le 29 juin 2017 à 15:16, Jaikiran Pai <[hidden email]> a
> >>> écrit :
> >>>>
> >>>>
> >>>> On 29-Jun-2017, at 3:58 PM, Nicolas Lalevée <
> [hidden email]>
> >>> wrote:
> >>>>
> >>>>>
> >>>>>> Le 29 juin 2017 à 07:59, Jaikiran Pai <[hidden email]> a
> >>> écrit :
> >>>>>>
> >>>>>> A quick update on this one - I finished off the “settings” sections
> >>> last week. There is only one pending item that I’m trying to address in
> >>> that section. The “Settings” page[1] has a “Settings File Structure”
> >>> section which tries to represent the Ivy settings XML file structure
> as a
> >>> tree. We have a similar one, one place else too (in Ivy file page). We
> use
> >>> a source code block to represent it. However, Asciidoc source code
> blocks
> >>> are rendered literally, so it won’t show up the links (as you’ll see in
> >>> that page[1] currently). For the Ivy page, I used “lists” to render the
> >>> structure and that was “good enough"[2]. However, I can’t use the same
> here
> >>> since Asciidoc (backed by asciidoctor generator) allows a max list
> depth of
> >>> 5 which means that any nested elements that exceed that depth won’t be
> >>> rendered correctly as a tree. The settings file structure goes beyond
> that
> >>> depth limit so it doesn’t work out well here.
> >>>>>>
> >>>>>> Ultimately, we either have to remove that section (there’s already a
> >>> “Child elements” section which _almost_ conveys the same thing) or
> come up
> >>> with a custom asciidoc “tree” kind of block element to render this. Any
> >>> thoughts?
> >>>>>
> >>>>> If I count correctly, there are 6 levels. So could we just remove the
> >>> root element from the tree so we save one level ? The root would be
> just
> >>> printed as some text. Could it then display correctly ?
> >>>>>
> >>>>
> >>>> That suggestion actually worked well. I went ahead and did that change
> >>> and regenerated the latest “master” site. It looks good
> >>> http://ant.apache.org/ivy/history/master/settings.html.
> >>>>
> >>>> -Jaikiran
> >>>>
> >>>>
> >>>>
> >>>> ---------------------------------------------------------------------
> >>>> 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
|

Re: Ivy - we have now moved to asciidoc for docs

Gintautas Grigelionis
In reply to this post by Jaikiran Pai
> Probably a thing to improve are all the « since 2.x » annotations. Maybe
we can have a macro for that, which will render everywhere the same, and
which will be placed everywhere the same. Now sometimes it is at the
beginning of the line, sometimes at the end, sometimes above. And I find it
being black bold a little too much.

Isn't that what CSS is for? ".ivy2x:before", anyone?

Gintas

P.S. I'm planing to work on generics in core, then tackle SVG. Otherwise, I
can just push the new Ivy logo in SVG, so everybody could get used to the
not-so-limbless ant :-)
12