ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicolas Lalevée <nicolas.lale...@hibnet.org>
Subject Re: Ivy - we have now moved to asciidoc for docs
Date Thu, 29 Jun 2017 10:28:54 GMT

> Le 29 juin 2017 à 07:59, Jaikiran Pai <jai.forums2013@gmail.com> 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 <nicolas.lalevee@hibnet.org> 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: dev-unsubscribe@ant.apache.org
> For additional commands, e-mail: dev-help@ant.apache.org
> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
> For additional commands, e-mail: dev-help@ant.apache.org
> 


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message