Migrating Ivy and IvyDE site to asciidoc

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

Migrating Ivy and IvyDE site to asciidoc

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

Reply | Threaded
Open this post in threaded view
|

Re: Migrating Ivy and IvyDE site to asciidoc

Matt Sicker
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 <[hidden email]>
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 <[hidden email]>
Reply | Threaded
Open this post in threaded view
|

Re: Migrating Ivy and IvyDE site to asciidoc

Nicolas Lalevée


> Le 23 avr. 2018 à 17:23, Matt Sicker <[hidden email]> 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 <[hidden email]>
> 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 <[hidden email]>


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

Reply | Threaded
Open this post in threaded view
|

Re: Migrating Ivy and IvyDE site to asciidoc

Matt Sicker
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 <[hidden email]>
wrote:

>
>
> > Le 23 avr. 2018 à 17:23, Matt Sicker <[hidden email]> 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 <[hidden email]>
> > 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 <[hidden email]>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>


--
Matt Sicker <[hidden email]>
Reply | Threaded
Open this post in threaded view
|

Re: Migrating Ivy and IvyDE site to asciidoc

Gintautas Grigelionis
In reply to this post by Nicolas Lalevée
2018-04-23 15:25 GMT+02:00 Nicolas Lalevée <[hidden email]>:

> 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
Reply | Threaded
Open this post in threaded view
|

Re: Migrating Ivy and IvyDE site to asciidoc

Nicolas Lalevée

> Le 7 mai 2018 à 08:24, Gintautas Grigelionis <[hidden email]> a écrit :
>
> 2018-04-23 15:25 GMT+02:00 Nicolas Lalevée <[hidden email]>:
>
>> 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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Migrating Ivy and IvyDE site to asciidoc

Matt Sicker
On 7 May 2018 at 06:17, Nicolas Lalevée <[hidden email]> 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 <[hidden email]>
Reply | Threaded
Open this post in threaded view
|

Re: Migrating Ivy and IvyDE site to asciidoc

Gintautas Grigelionis
In reply to this post by Nicolas Lalevée
2018-05-07 13:17 GMT+02:00 Nicolas Lalevée <[hidden email]>:

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