You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by Nicolas Lalevée <ni...@hibnet.org> on 2018/04/23 13:25:30 UTC
Migrating Ivy and IvyDE site to asciidoc
Hi,
I would like to go forward and migrate the part of the site about Ivy and IvyDE to asciidoc, since it has gone well for the documentation about Ivy and IvyDE.
So first, is OK for everybody ?
Reminding of the pros: way faster, more standard source of doc. For the cons: not 'html-hackable’ easily, see below about the home page.
For a first base of the discussion, I have give it a shot. I have reused the xooki2asciidoc tool developed for Ivy's documentation. And I have done a first run, committed the result of the asciidoc files. I think that since the amount of the pages is reasonable, the quality is fine enough and can fix the page manually from there.
You can see the generated site from the asciidoc files with: ant -f build-doc.xml generate-site
The new site is generated in a ‘production2’ folder, so we do not mess with the real site. It is only for testing purpose for now.
There are some cleanup to do, I haven't fix any page manually. If somebody want to start, he is welcome to do so.
One page I am worried about is the main page [2]. I am not sure there are some sane asciidoc directives to render something similar. If you already have ideas, please share. If I remember correctly there is directive to blindly render content, which could be html, as a fall back.
Then, if we’re OK with the change, and if we find something suitable to generate the Home page, we prepare a new version of the site, pushing somewhere so we can review it online. Once happy with the result, we switch. And then we apply the same process with the site for IvyDE. Sounds good ?
Nicolas
[1] http://ant.apache.org/ivy/index.html <http://ant.apache.org/ivy/index.html>
Re: Migrating Ivy and IvyDE site to asciidoc
Posted by Matt Sicker <bo...@gmail.com>.
On 7 May 2018 at 06:17, Nicolas Lalevée <ni...@hibnet.org> wrote:
> The issue isn’t about the format of the image but about the layout of the
> page. If you have some proof of concept of how a home page can be done in
> asciidoc, please share, in a gist of whatever.
>
I used asciidoc with maven-site-plugin in log4j:
https://github.com/apache/logging-log4j2/blob/master/src/site/asciidoc/index.adoc
https://github.com/apache/logging-log4j2/blob/master/src/site/site.vm
--
Matt Sicker <bo...@gmail.com>
Re: Migrating Ivy and IvyDE site to asciidoc
Posted by Gintautas Grigelionis <g....@gmail.com>.
2018-05-07 13:17 GMT+02:00 Nicolas Lalevée <ni...@hibnet.org>:
> The issue isn’t about the format of the image but about the layout of the
> page. If you have some proof of concept of how a home page can be done in
> asciidoc, please share, in a gist of whatever.
Which part of the front page is tricky? I guess it would be easiest to keep
the four links/icons in the table as they are now; otherwise one could try
something like a float
group -- only to come to conclusion that images must be cropped
appropriately to align them properly -- at which point one may start
thinking of SVG :-) not to mention a custom CSS.
Gintas
[.float-group]
--
:figure-caption!:
.https://ant.apache.org/ivy/download.html[download]
image::https://ant.apache.org/ivy/images/ivy-dl-2.5.0-rc1.png[float=left,link=https://ant.apache.org/ivy/download.html]
.https://ant.apache.org/ivy/history/latest-milestone/index.html[documentation
+++<br>+++ & tutorials]
image::https://ant.apache.org/ivy/images/ivy-book.png[float=left,link=https://ant.apache.org/ivy/history/latest-milestone/index.html]
.https://ant.apache.org/ivy/demo.html[demo]
image::https://ant.apache.org/ivy/images/ivy-demo.png[float=left,link=https://ant.apache.org/ivy/demo.html]
.https://ant.apache.org/ivy/mailing-lists.html[share your experience]
image::https://ant.apache.org/ivy/images/ivy-forum.png[float=left,link=https://ant.apache.org/ivy/mailing-lists.html]
--
Re: Migrating Ivy and IvyDE site to asciidoc
Posted by Nicolas Lalevée <ni...@hibnet.org>.
> Le 7 mai 2018 à 08:24, Gintautas Grigelionis <g....@gmail.com> a écrit :
>
> 2018-04-23 15:25 GMT+02:00 Nicolas Lalevée <ni...@hibnet.org>:
>
>> One page I am worried about is the main page [2]. I am not sure there are
>> some sane asciidoc directives to render something similar. If you already
>> have ideas, please share. If I remember correctly there is directive to
>> blindly render content, which could be html, as a fall back.
>>
>
> I'd like to see more SVG :-) So, how about replacing the four images
> (download, demo, manual, forum)? Then, style them as a flexbox for
> responsivity.
The issue isn’t about the format of the image but about the layout of the page. If you have some proof of concept of how a home page can be done in asciidoc, please share, in a gist of whatever.
Nicolas
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Migrating Ivy and IvyDE site to asciidoc
Posted by Gintautas Grigelionis <g....@gmail.com>.
2018-04-23 15:25 GMT+02:00 Nicolas Lalevée <ni...@hibnet.org>:
> One page I am worried about is the main page [2]. I am not sure there are
> some sane asciidoc directives to render something similar. If you already
> have ideas, please share. If I remember correctly there is directive to
> blindly render content, which could be html, as a fall back.
>
I'd like to see more SVG :-) So, how about replacing the four images
(download, demo, manual, forum)? Then, style them as a flexbox for
responsivity.
Gintas
Re: Migrating Ivy and IvyDE site to asciidoc
Posted by Matt Sicker <bo...@gmail.com>.
I haven't looked at that xooki thing, that might work better for all I
know. Interesting :)
On 23 April 2018 at 10:38, Nicolas Lalevée <ni...@hibnet.org>
wrote:
>
>
> > Le 23 avr. 2018 à 17:23, Matt Sicker <bo...@gmail.com> a écrit :
> >
> > For what it's worth, I used pandoc <https://pandoc.org> to automate
> most of
> > the conversion from xdoc and markdown to asciidoc over at Log4j. The only
> > struggles I had with that tool are that it supports HTML, not xdoc, so it
> > doesn't understand the section/subsection/etc. tags, and it doesn't
> output
> > the correct syntax for nested tables (need to convert | to ! in a nested
> > table).
>
> Very interesting.
> I won’t have time to investigate if it is useful here, since xooki2ascii
> is working. But if pandoc can do a better job, I am all ears.
> At least next time I’ll probably start with that.
>
> Nicolas
>
> >
> > On 23 April 2018 at 08:25, Nicolas Lalevée <ni...@hibnet.org>
> > wrote:
> >
> >> Hi,
> >>
> >> I would like to go forward and migrate the part of the site about Ivy
> and
> >> IvyDE to asciidoc, since it has gone well for the documentation about
> Ivy
> >> and IvyDE.
> >>
> >> So first, is OK for everybody ?
> >> Reminding of the pros: way faster, more standard source of doc. For the
> >> cons: not 'html-hackable’ easily, see below about the home page.
> >>
> >> For a first base of the discussion, I have give it a shot. I have reused
> >> the xooki2asciidoc tool developed for Ivy's documentation. And I have
> done
> >> a first run, committed the result of the asciidoc files. I think that
> since
> >> the amount of the pages is reasonable, the quality is fine enough and
> can
> >> fix the page manually from there.
> >>
> >> You can see the generated site from the asciidoc files with: ant -f
> >> build-doc.xml generate-site
> >> The new site is generated in a ‘production2’ folder, so we do not mess
> >> with the real site. It is only for testing purpose for now.
> >>
> >> There are some cleanup to do, I haven't fix any page manually. If
> somebody
> >> want to start, he is welcome to do so.
> >>
> >> One page I am worried about is the main page [2]. I am not sure there
> are
> >> some sane asciidoc directives to render something similar. If you
> already
> >> have ideas, please share. If I remember correctly there is directive to
> >> blindly render content, which could be html, as a fall back.
> >>
> >> Then, if we’re OK with the change, and if we find something suitable to
> >> generate the Home page, we prepare a new version of the site, pushing
> >> somewhere so we can review it online. Once happy with the result, we
> >> switch. And then we apply the same process with the site for IvyDE.
> Sounds
> >> good ?
> >>
> >> Nicolas
> >>
> >> [1] http://ant.apache.org/ivy/index.html <http://ant.apache.org/ivy/
> >> index.html>
> >>
> >>
> >
> >
> > --
> > Matt Sicker <bo...@gmail.com>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
> For additional commands, e-mail: dev-help@ant.apache.org
>
>
--
Matt Sicker <bo...@gmail.com>
Re: Migrating Ivy and IvyDE site to asciidoc
Posted by Nicolas Lalevée <ni...@hibnet.org>.
> Le 23 avr. 2018 à 17:23, Matt Sicker <bo...@gmail.com> a écrit :
>
> For what it's worth, I used pandoc <https://pandoc.org> to automate most of
> the conversion from xdoc and markdown to asciidoc over at Log4j. The only
> struggles I had with that tool are that it supports HTML, not xdoc, so it
> doesn't understand the section/subsection/etc. tags, and it doesn't output
> the correct syntax for nested tables (need to convert | to ! in a nested
> table).
Very interesting.
I won’t have time to investigate if it is useful here, since xooki2ascii is working. But if pandoc can do a better job, I am all ears.
At least next time I’ll probably start with that.
Nicolas
>
> On 23 April 2018 at 08:25, Nicolas Lalevée <ni...@hibnet.org>
> wrote:
>
>> Hi,
>>
>> I would like to go forward and migrate the part of the site about Ivy and
>> IvyDE to asciidoc, since it has gone well for the documentation about Ivy
>> and IvyDE.
>>
>> So first, is OK for everybody ?
>> Reminding of the pros: way faster, more standard source of doc. For the
>> cons: not 'html-hackable’ easily, see below about the home page.
>>
>> For a first base of the discussion, I have give it a shot. I have reused
>> the xooki2asciidoc tool developed for Ivy's documentation. And I have done
>> a first run, committed the result of the asciidoc files. I think that since
>> the amount of the pages is reasonable, the quality is fine enough and can
>> fix the page manually from there.
>>
>> You can see the generated site from the asciidoc files with: ant -f
>> build-doc.xml generate-site
>> The new site is generated in a ‘production2’ folder, so we do not mess
>> with the real site. It is only for testing purpose for now.
>>
>> There are some cleanup to do, I haven't fix any page manually. If somebody
>> want to start, he is welcome to do so.
>>
>> One page I am worried about is the main page [2]. I am not sure there are
>> some sane asciidoc directives to render something similar. If you already
>> have ideas, please share. If I remember correctly there is directive to
>> blindly render content, which could be html, as a fall back.
>>
>> Then, if we’re OK with the change, and if we find something suitable to
>> generate the Home page, we prepare a new version of the site, pushing
>> somewhere so we can review it online. Once happy with the result, we
>> switch. And then we apply the same process with the site for IvyDE. Sounds
>> good ?
>>
>> Nicolas
>>
>> [1] http://ant.apache.org/ivy/index.html <http://ant.apache.org/ivy/
>> index.html>
>>
>>
>
>
> --
> Matt Sicker <bo...@gmail.com>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Migrating Ivy and IvyDE site to asciidoc
Posted by Matt Sicker <bo...@gmail.com>.
For what it's worth, I used pandoc <https://pandoc.org> to automate most of
the conversion from xdoc and markdown to asciidoc over at Log4j. The only
struggles I had with that tool are that it supports HTML, not xdoc, so it
doesn't understand the section/subsection/etc. tags, and it doesn't output
the correct syntax for nested tables (need to convert | to ! in a nested
table).
On 23 April 2018 at 08:25, Nicolas Lalevée <ni...@hibnet.org>
wrote:
> Hi,
>
> I would like to go forward and migrate the part of the site about Ivy and
> IvyDE to asciidoc, since it has gone well for the documentation about Ivy
> and IvyDE.
>
> So first, is OK for everybody ?
> Reminding of the pros: way faster, more standard source of doc. For the
> cons: not 'html-hackable’ easily, see below about the home page.
>
> For a first base of the discussion, I have give it a shot. I have reused
> the xooki2asciidoc tool developed for Ivy's documentation. And I have done
> a first run, committed the result of the asciidoc files. I think that since
> the amount of the pages is reasonable, the quality is fine enough and can
> fix the page manually from there.
>
> You can see the generated site from the asciidoc files with: ant -f
> build-doc.xml generate-site
> The new site is generated in a ‘production2’ folder, so we do not mess
> with the real site. It is only for testing purpose for now.
>
> There are some cleanup to do, I haven't fix any page manually. If somebody
> want to start, he is welcome to do so.
>
> One page I am worried about is the main page [2]. I am not sure there are
> some sane asciidoc directives to render something similar. If you already
> have ideas, please share. If I remember correctly there is directive to
> blindly render content, which could be html, as a fall back.
>
> Then, if we’re OK with the change, and if we find something suitable to
> generate the Home page, we prepare a new version of the site, pushing
> somewhere so we can review it online. Once happy with the result, we
> switch. And then we apply the same process with the site for IvyDE. Sounds
> good ?
>
> Nicolas
>
> [1] http://ant.apache.org/ivy/index.html <http://ant.apache.org/ivy/
> index.html>
>
>
--
Matt Sicker <bo...@gmail.com>