You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@deltaspike.apache.org by Rafael Benevides <be...@redhat.com> on 2014/09/11 19:49:25 UTC
Document migration : Markdown to Asciidoc / SVN to Git
Hi all,
I worked on documentation migration from MarkDown to Asciidoc.
- The syntax-highlighter was checked
- The intra-document links was checked
- The the anchor links was checked
- The table format was checked
- Minor adjustments needed
The sources were placed here until we complete the review:
https://github.com/rafabene/deltaspike/tree/asciidoc-migration/documentation/src/main/asciidoc
They were published at http://deltaspike.apache.org/documentation/
Once that they got merged to Git, the SVN files should be removed to
avoid any misunderstood.
Please, let me know if you find any issues.
Thanks
--
*Rafael Benevides | Senior Software Engineer*
JBoss Developer
M: +55-61-9269-6576
Red Hat
Better technology. Faster innovation. Powered by community collaboration.
See how it works at www.redhat.com <http://www.redhat.com/>
LinkedIn <http://www.linkedin.com/company/3258288> Youtube
<https://www.youtube.com/redhatlatam>
Re: Document migration : Markdown to Asciidoc / SVN to Git
Posted by Gerhard Petracek <ge...@gmail.com>.
hi rafael,
it is in the file - yes - and on our final site it should get rendered as
html-comment instead of skipping it like github is doing it.
regards,
gerhard
2014-09-12 14:23 GMT+02:00 Rafael Benevides <be...@redhat.com>:
> Updated to asciidoctor 1.5
>
> Gerhard,
>
> How do you mean "the final pages should also contain the license header"
> ???
>
> I didn't understand because The license header is already there at html
> source[1] and at the document sources as well[2]
>
> [1] http://deltaspike.apache.org/documentation/
> [2] https://github.com/rafabene/deltaspike/tree/asciidoc-
> migration/documentation/src/main/asciidoc
>
> Thanks
>
> Em 9/12/14, 5:32, Gerhard Petracek escreveu:
>
> hi rafael,
>>
>> thx - it's great to see the progress!
>> if it isn't on your list already: the final pages should also contain the
>> license header (at least as a comment - see our current pages).
>>
>> regards,
>> gerhard
>>
>>
>>
>> 2014-09-11 23:15 GMT+02:00 Rafael Benevides <be...@redhat.com>:
>>
>> Hi John!
>>>
>>> Em 9/11/14, 15:23, John D. Ament escreveu:
>>>
>>> Rafael,
>>>>
>>>> Couple of things I'd recommend.
>>>>
>>>> - We should put the documentation adoc's in a documentation folder.
>>>> This
>>>> will allow us to upload to different folders, as I'm sure we'll want to
>>>> cut
>>>> over the remaining parts of the site to adoc to make it more consistent
>>>> and
>>>> easier to update. We'll also have to turn on the preserveDirectories
>>>> option in the maven plugin.
>>>>
>>>> Good point. But them then we should change the name of the folder to
>>> something else but REPO_ROOT/documentation.
>>> My idea is that We could start with the documentation first and update it
>>> later as our needs. My idea is to have at least the documentation
>>> migrated
>>> ASAP.
>>> Agreed ?
>>>
>>> - Can we upgrade to asciidoctor 1.5.0? The only issue I saw was a
>>>> removed import in the template erb file.
>>>>
>>>> I had issues with asciidoctor 1.5.0. I'll investigate it tomorrow.
>>>
>>> - I'm a bit concerned with us uploading to the doc site before the
>>>> source
>>>> files are checked in. this is something we'll likely need to work out
>>>> via
>>>> process.
>>>>
>>>> +1 for "this is something we'll likely need to work out via process."
>>>
>>> - To delete the current files, we need to update the links on the page
>>>> to
>>>> go to /documentation.
>>>>
>>>> +1. I can do that after the proposed branch got merged to upstream.
>>>
>>> I'm also wondering if we should now introduce a top level pom that can
>>>> be
>>>> used during releases to ensure the docs get properly versioned. Then we
>>>> can execute a release and upload the site during the release process.
>>>>
>>>> I believe that a top level pom is helpful and we could also make the
>>> documentation part of the distribution zip. But that should be a second
>>> step handled by another Jira ticket and separated from this migration
>>> step.
>>>
>>> John
>>>>
>>>> On Thu, Sep 11, 2014 at 1:49 PM, Rafael Benevides <benevides@redhat.com
>>>> <ma...@redhat.com>> wrote:
>>>>
>>>> Hi all,
>>>>
>>>> I worked on documentation migration from MarkDown to Asciidoc.
>>>>
>>>> - The syntax-highlighter was checked
>>>> - The intra-document links was checked
>>>> - The the anchor links was checked
>>>> - The table format was checked
>>>> - Minor adjustments needed
>>>>
>>>> The sources were placed here until we complete the review:
>>>> https://github.com/rafabene/deltaspike/tree/asciidoc-
>>>> migration/documentation/src/main/asciidoc
>>>>
>>>> They were published at http://deltaspike.apache.org/documentation/
>>>>
>>>> Once that they got merged to Git, the SVN files should be removed
>>>> to avoid any misunderstood.
>>>>
>>>> Please, let me know if you find any issues.
>>>>
>>>> Thanks
>>>>
>>>>
>>>> --
>>>> *Rafael Benevides | Senior Software Engineer*
>>>> JBoss Developer
>>>> M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>>>>
>>>> Red Hat
>>>>
>>>> Better technology. Faster innovation. Powered by community
>>>> collaboration.
>>>> See how it works at www.redhat.com <http://www.redhat.com/>
>>>>
>>>> LinkedIn <http://www.linkedin.com/company/3258288> Youtube
>>>> <https://www.youtube.com/redhatlatam>
>>>>
>>>>
>>>>
>>>>
>
Re: Document migration : Markdown to Asciidoc / SVN to Git
Posted by Rafael Benevides <be...@redhat.com>.
Updated to asciidoctor 1.5
Gerhard,
How do you mean "the final pages should also contain the license header" ???
I didn't understand because The license header is already there at html
source[1] and at the document sources as well[2]
[1] http://deltaspike.apache.org/documentation/
[2]
https://github.com/rafabene/deltaspike/tree/asciidoc-migration/documentation/src/main/asciidoc
Thanks
Em 9/12/14, 5:32, Gerhard Petracek escreveu:
> hi rafael,
>
> thx - it's great to see the progress!
> if it isn't on your list already: the final pages should also contain the
> license header (at least as a comment - see our current pages).
>
> regards,
> gerhard
>
>
>
> 2014-09-11 23:15 GMT+02:00 Rafael Benevides <be...@redhat.com>:
>
>> Hi John!
>>
>> Em 9/11/14, 15:23, John D. Ament escreveu:
>>
>>> Rafael,
>>>
>>> Couple of things I'd recommend.
>>>
>>> - We should put the documentation adoc's in a documentation folder. This
>>> will allow us to upload to different folders, as I'm sure we'll want to cut
>>> over the remaining parts of the site to adoc to make it more consistent and
>>> easier to update. We'll also have to turn on the preserveDirectories
>>> option in the maven plugin.
>>>
>> Good point. But them then we should change the name of the folder to
>> something else but REPO_ROOT/documentation.
>> My idea is that We could start with the documentation first and update it
>> later as our needs. My idea is to have at least the documentation migrated
>> ASAP.
>> Agreed ?
>>
>>> - Can we upgrade to asciidoctor 1.5.0? The only issue I saw was a
>>> removed import in the template erb file.
>>>
>> I had issues with asciidoctor 1.5.0. I'll investigate it tomorrow.
>>
>>> - I'm a bit concerned with us uploading to the doc site before the source
>>> files are checked in. this is something we'll likely need to work out via
>>> process.
>>>
>> +1 for "this is something we'll likely need to work out via process."
>>
>>> - To delete the current files, we need to update the links on the page to
>>> go to /documentation.
>>>
>> +1. I can do that after the proposed branch got merged to upstream.
>>
>>> I'm also wondering if we should now introduce a top level pom that can be
>>> used during releases to ensure the docs get properly versioned. Then we
>>> can execute a release and upload the site during the release process.
>>>
>> I believe that a top level pom is helpful and we could also make the
>> documentation part of the distribution zip. But that should be a second
>> step handled by another Jira ticket and separated from this migration step.
>>
>>> John
>>>
>>> On Thu, Sep 11, 2014 at 1:49 PM, Rafael Benevides <benevides@redhat.com
>>> <ma...@redhat.com>> wrote:
>>>
>>> Hi all,
>>>
>>> I worked on documentation migration from MarkDown to Asciidoc.
>>>
>>> - The syntax-highlighter was checked
>>> - The intra-document links was checked
>>> - The the anchor links was checked
>>> - The table format was checked
>>> - Minor adjustments needed
>>>
>>> The sources were placed here until we complete the review:
>>> https://github.com/rafabene/deltaspike/tree/asciidoc-
>>> migration/documentation/src/main/asciidoc
>>>
>>> They were published at http://deltaspike.apache.org/documentation/
>>>
>>> Once that they got merged to Git, the SVN files should be removed
>>> to avoid any misunderstood.
>>>
>>> Please, let me know if you find any issues.
>>>
>>> Thanks
>>>
>>>
>>> --
>>> *Rafael Benevides | Senior Software Engineer*
>>> JBoss Developer
>>> M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>>>
>>> Red Hat
>>>
>>> Better technology. Faster innovation. Powered by community
>>> collaboration.
>>> See how it works at www.redhat.com <http://www.redhat.com/>
>>>
>>> LinkedIn <http://www.linkedin.com/company/3258288> Youtube
>>> <https://www.youtube.com/redhatlatam>
>>>
>>>
>>>
Re: Document migration : Markdown to Asciidoc / SVN to Git
Posted by Gerhard Petracek <ge...@gmail.com>.
hi rafael,
thx - it's great to see the progress!
if it isn't on your list already: the final pages should also contain the
license header (at least as a comment - see our current pages).
regards,
gerhard
2014-09-11 23:15 GMT+02:00 Rafael Benevides <be...@redhat.com>:
> Hi John!
>
> Em 9/11/14, 15:23, John D. Ament escreveu:
>
>> Rafael,
>>
>> Couple of things I'd recommend.
>>
>> - We should put the documentation adoc's in a documentation folder. This
>> will allow us to upload to different folders, as I'm sure we'll want to cut
>> over the remaining parts of the site to adoc to make it more consistent and
>> easier to update. We'll also have to turn on the preserveDirectories
>> option in the maven plugin.
>>
> Good point. But them then we should change the name of the folder to
> something else but REPO_ROOT/documentation.
> My idea is that We could start with the documentation first and update it
> later as our needs. My idea is to have at least the documentation migrated
> ASAP.
> Agreed ?
>
>> - Can we upgrade to asciidoctor 1.5.0? The only issue I saw was a
>> removed import in the template erb file.
>>
> I had issues with asciidoctor 1.5.0. I'll investigate it tomorrow.
>
>> - I'm a bit concerned with us uploading to the doc site before the source
>> files are checked in. this is something we'll likely need to work out via
>> process.
>>
> +1 for "this is something we'll likely need to work out via process."
>
>> - To delete the current files, we need to update the links on the page to
>> go to /documentation.
>>
> +1. I can do that after the proposed branch got merged to upstream.
>
>>
>> I'm also wondering if we should now introduce a top level pom that can be
>> used during releases to ensure the docs get properly versioned. Then we
>> can execute a release and upload the site during the release process.
>>
> I believe that a top level pom is helpful and we could also make the
> documentation part of the distribution zip. But that should be a second
> step handled by another Jira ticket and separated from this migration step.
>
>>
>> John
>>
>> On Thu, Sep 11, 2014 at 1:49 PM, Rafael Benevides <benevides@redhat.com
>> <ma...@redhat.com>> wrote:
>>
>> Hi all,
>>
>> I worked on documentation migration from MarkDown to Asciidoc.
>>
>> - The syntax-highlighter was checked
>> - The intra-document links was checked
>> - The the anchor links was checked
>> - The table format was checked
>> - Minor adjustments needed
>>
>> The sources were placed here until we complete the review:
>> https://github.com/rafabene/deltaspike/tree/asciidoc-
>> migration/documentation/src/main/asciidoc
>>
>> They were published at http://deltaspike.apache.org/documentation/
>>
>> Once that they got merged to Git, the SVN files should be removed
>> to avoid any misunderstood.
>>
>> Please, let me know if you find any issues.
>>
>> Thanks
>>
>>
>> --
>> *Rafael Benevides | Senior Software Engineer*
>> JBoss Developer
>> M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>>
>> Red Hat
>>
>> Better technology. Faster innovation. Powered by community
>> collaboration.
>> See how it works at www.redhat.com <http://www.redhat.com/>
>>
>> LinkedIn <http://www.linkedin.com/company/3258288> Youtube
>> <https://www.youtube.com/redhatlatam>
>>
>>
>>
>
Re: Document migration : Markdown to Asciidoc / SVN to Git
Posted by Rafael Benevides <be...@redhat.com>.
Hi John!
Em 9/11/14, 15:23, John D. Ament escreveu:
> Rafael,
>
> Couple of things I'd recommend.
>
> - We should put the documentation adoc's in a documentation folder.
> This will allow us to upload to different folders, as I'm sure we'll
> want to cut over the remaining parts of the site to adoc to make it
> more consistent and easier to update. We'll also have to turn on the
> preserveDirectories option in the maven plugin.
Good point. But them then we should change the name of the folder to
something else but REPO_ROOT/documentation.
My idea is that We could start with the documentation first and update
it later as our needs. My idea is to have at least the documentation
migrated ASAP.
Agreed ?
> - Can we upgrade to asciidoctor 1.5.0? The only issue I saw was a
> removed import in the template erb file.
I had issues with asciidoctor 1.5.0. I'll investigate it tomorrow.
> - I'm a bit concerned with us uploading to the doc site before the
> source files are checked in. this is something we'll likely need to
> work out via process.
+1 for "this is something we'll likely need to work out via process."
> - To delete the current files, we need to update the links on the page
> to go to /documentation.
+1. I can do that after the proposed branch got merged to upstream.
>
> I'm also wondering if we should now introduce a top level pom that can
> be used during releases to ensure the docs get properly versioned.
> Then we can execute a release and upload the site during the release
> process.
I believe that a top level pom is helpful and we could also make the
documentation part of the distribution zip. But that should be a second
step handled by another Jira ticket and separated from this migration step.
>
> John
>
> On Thu, Sep 11, 2014 at 1:49 PM, Rafael Benevides
> <benevides@redhat.com <ma...@redhat.com>> wrote:
>
> Hi all,
>
> I worked on documentation migration from MarkDown to Asciidoc.
>
> - The syntax-highlighter was checked
> - The intra-document links was checked
> - The the anchor links was checked
> - The table format was checked
> - Minor adjustments needed
>
> The sources were placed here until we complete the review:
> https://github.com/rafabene/deltaspike/tree/asciidoc-migration/documentation/src/main/asciidoc
>
> They were published at http://deltaspike.apache.org/documentation/
>
> Once that they got merged to Git, the SVN files should be removed
> to avoid any misunderstood.
>
> Please, let me know if you find any issues.
>
> Thanks
>
>
> --
>
> *Rafael Benevides | Senior Software Engineer*
> JBoss Developer
> M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>
> Red Hat
>
> Better technology. Faster innovation. Powered by community
> collaboration.
> See how it works at www.redhat.com <http://www.redhat.com/>
>
> LinkedIn <http://www.linkedin.com/company/3258288> Youtube
> <https://www.youtube.com/redhatlatam>
>
>
Re: Document migration : Markdown to Asciidoc / SVN to Git
Posted by "John D. Ament" <jo...@gmail.com>.
Rafael,
Couple of things I'd recommend.
- We should put the documentation adoc's in a documentation folder. This
will allow us to upload to different folders, as I'm sure we'll want to cut
over the remaining parts of the site to adoc to make it more consistent and
easier to update. We'll also have to turn on the preserveDirectories
option in the maven plugin.
- Can we upgrade to asciidoctor 1.5.0? The only issue I saw was a removed
import in the template erb file.
- I'm a bit concerned with us uploading to the doc site before the source
files are checked in. this is something we'll likely need to work out via
process.
- To delete the current files, we need to update the links on the page to
go to /documentation.
I'm also wondering if we should now introduce a top level pom that can be
used during releases to ensure the docs get properly versioned. Then we
can execute a release and upload the site during the release process.
John
On Thu, Sep 11, 2014 at 1:49 PM, Rafael Benevides <be...@redhat.com>
wrote:
> Hi all,
>
> I worked on documentation migration from MarkDown to Asciidoc.
>
> - The syntax-highlighter was checked
> - The intra-document links was checked
> - The the anchor links was checked
> - The table format was checked
> - Minor adjustments needed
>
> The sources were placed here until we complete the review:
> https://github.com/rafabene/deltaspike/tree/asciidoc-migration/documentation/src/main/asciidoc
>
> They were published at http://deltaspike.apache.org/documentation/
>
> Once that they got merged to Git, the SVN files should be removed to avoid
> any misunderstood.
>
> Please, let me know if you find any issues.
>
> Thanks
>
>
> --
>
> *Rafael Benevides | Senior Software Engineer*
> JBoss Developer
> M: +55-61-9269-6576
>
> [image: Red Hat]
>
> Better technology. Faster innovation. Powered by community collaboration.
> See how it works at www.redhat.com
>
> [image: LinkedIn] <http://www.linkedin.com/company/3258288> [image:
> Youtube] <https://www.youtube.com/redhatlatam>
>