You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@roller.apache.org by Swapnil M Mane <sw...@apache.org> on 2020/05/02 17:53:36 UTC
Re: Roller Documentation from ODT to md (markdown)
Hello team,
Here is the translation of the 'User Guide' document [1] from ODT to AsciiDoc.
It can be referred at
https://github.com/apache/roller/blob/master/docs/roller-user-guide.adoc
This includes the screenshot of our *new* design and theme for Roller UI :)
With this translation, all our ODT documents are converted to AsciiDoc.
Here is the ticket, we used for this translation,
https://issues.apache.org/jira/browse/ROL-2151
If you found any issue or improvement in this translation, please feel
free to report at ROL-2151.
Thanks so much, everyone for your support on this.
Best regards,
Swapnil M Mane,
www.apache.org
On Mon, Mar 2, 2020 at 10:32 AM Swapnil M Mane <sw...@apache.org> wrote:
>
> Thank you Dave! :)
>
> Hi Team,
> The translation of 'Template Guide' document [1] from ODT to AsciiDoc
> is committed in the Roller 'master' branch at following MR
> https://github.com/apache/roller/pull/56
> and can be referred at
> https://github.com/apache/roller/blob/master/docs/roller-template-guide.adoc
>
> Best regards,
> Swapnil M Mane,
> www.apache.org
> On Sun, Mar 1, 2020 at 11:53 PM Dave <sn...@gmail.com> wrote:
> >
> > Swapnil,
> >
> > This looks great, and with updated screenshots! Thanks for doing this work.
> > It looks nicer and is so much better than having to deal with ODT.
> >
> > Dave
> >
> > On Sat, Feb 22, 2020 at 8:41 AM Swapnil M Mane <sw...@apache.org>
> > wrote:
> >
> > > Hello team,
> > >
> > > Here is the translation of 'Template Guide' document [1] from ODT to
> > > AsciiDoc.
> > > It can be referred at
> > >
> > > https://github.com/swapnilmmane/roller/blob/master/docs/roller-template-guide.adoc
> > >
> > > This time, it was completely manual work, automation didn't worked
> > > because it has various tables and other formatting issues.
> > >
> > > I have done the following changes in the new document:
> > > 1.) Updated the images are per our new Roller UI.
> > > 2.) Since the UI workflow and options of customizing theme and
> > > templated are changed in our new Roller UI, thus updated the content
> > > as per the new workflow. The updated content can be referred at
> > > https://s.apache.org/g0m8y
> > >
> > > Kindly have a look and help us in reviewing, I am planning to commit
> > > at the end of next week.
> > >
> > > [1]
> > > https://github.com/apache/roller/blob/master/docs/roller-template-guide.odt
> > >
> > >
> > > Best regards,
> > > Swapnil M Mane,
> > > www.apache.org
> > > On Mon, Sep 23, 2019 at 3:27 PM Swapnil M Mane <sw...@apache.org>
> > > wrote:
> > > >
> > > > Thanks Dave, it's automated + manual work :)
> > > >
> > > > 1. First I convert ODT to md using
> > > > https://www.privatedaddy.com/convert_odt_to_md
> > > >
> > > > 2. Convert md file to as AsciiDoc using Pandoc.
> > > >
> > > > 3. The above process introduced various special characters, remove
> > > > images, and some code snippet issues, fix them manually.
> > > >
> > > > 4. Then, review the existing ODT and new AsciiDoc file line by line
> > > > and fix the issues.
> > > >
> > > > Best regards,
> > > > Swapnil M Mane,
> > > > www.apache.org
> > > >
> > > > On Sun, Sep 22, 2019 at 12:30 AM Dave <sn...@gmail.com> wrote:
> > > > >
> > > > > Thanks for doing this work, it looks great! Are you using any tools to
> > > > > automate the conversion?
> > > > >
> > > > > Dave
> > > > >
> > > > >
> > > > > On Wed, Sep 18, 2019 at 8:29 AM Swapnil M Mane <
> > > swapnilmmane@apache.org>
> > > > > wrote:
> > > > >
> > > > > > Hello team,
> > > > > >
> > > > > > Here comes our first translation from ODT to AsciiDoc.
> > > > > > The 'Installation Guide' document [1] is translated to AsciiDoc, it
> > > > > > can be referred at
> > > > > >
> > > > > >
> > > https://github.com/swapnilmmane/roller/blob/master/docs/roller-install-guide.adoc
> > > > > >
> > > > > > Before committing, I would like to get it reviewed from the
> > > community.
> > > > > > Please feel free to comment.
> > > > > >
> > > > > > P.S. I have removed the 'OpenDS project' mention from Acknowledgments
> > > > > > section since now we have converted the document to AsciiDoc.
> > > > > >
> > > > > > [1]
> > > > > >
> > > https://github.com/apache/roller/blob/master/docs/roller-install-guide.odt
> > > > > >
> > > > > >
> > > > > > Best regards,
> > > > > > Swapnil M Mane,
> > > > > > www.apache.org
> > > > > >
> > > > > > On Thu, Aug 29, 2019 at 5:44 PM Swapnil M Mane <
> > > swapnilmmane@apache.org>
> > > > > > wrote:
> > > > > > >
> > > > > > > Thank you Aditya.
> > > > > > >
> > > > > > > @Team,
> > > > > > > Here is the Jira to track the progress of this effort,
> > > > > > > https://issues.apache.org/jira/browse/ROL-2151
> > > > > > >
> > > > > > >
> > > > > > > Best regards,
> > > > > > > Swapnil M Mane,
> > > > > > > www.apache.org
> > > > > > >
> > > > > > > On Wed, Aug 28, 2019 at 12:50 PM Aditya Sharma <
> > > adityasharma@apache.org>
> > > > > > wrote:
> > > > > > > >
> > > > > > > > Big +1 for AsciiDoc
> > > > > > > >
> > > > > > > > Thanks and regards,
> > > > > > > > Aditya Sharma
> > > > > > > >
> > > > > > > > On Tue, 27 Aug 2019 at 23:36, Swapnil M Mane <
> > > swapnilmmane@apache.org>
> > > > > > > > wrote:
> > > > > > > >
> > > > > > > > > Sure Matt, thank you for the kind note.
> > > > > > > > > Will surely sync up with you in case of any issue.
> > > > > > > > > I also played with Asciidoctor in past, indeed a great tool!
> > > > > > > > >
> > > > > > > > >
> > > > > > > > > Best regards,
> > > > > > > > > Swapnil M Mane,
> > > > > > > > > www.apache.org
> > > > > > > > >
> > > > > > > > > On Tue, Aug 27, 2019 at 11:16 PM Matt Raible <
> > > matt@raibledesigns.com
> > > > > > >
> > > > > > > > > wrote:
> > > > > > > > > >
> > > > > > > > > > +1 for AsciiDoc! I have a lot of experience with
> > > Asciidoctor, so
> > > > > > let me
> > > > > > > > > know if you run into issues.
> > > > > > > > > >
> > > > > > > > > > Cheers,
> > > > > > > > > >
> > > > > > > > > > Matt
> > > > > > > > > >
> > > > > > > > > > > On Aug 27, 2019, at 11:06 AM, Swapnil M Mane <
> > > > > > swapnilmmane@apache.org>
> > > > > > > > > wrote:
> > > > > > > > > > >
> > > > > > > > > > > Great, thanks Dave.
> > > > > > > > > > >
> > > > > > > > > > > Thoughts travels, while drafting the mail, AsciiDoc was
> > > also in
> > > > > > my
> > > > > > > > > mind.
> > > > > > > > > > > And AsciiDoc is also having all the advantages mentioned
> > > above.
> > > > > > > > > > >
> > > > > > > > > > > After some more exploration, I am now more inclined towards
> > > > > > AsciiDoc.
> > > > > > > > > > > So, +1 for AsciiDoc.
> > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > > > Best regards,
> > > > > > > > > > > Swapnil M Mane,
> > > > > > > > > > > www.apache.org
> > > > > > > > > > >
> > > > > > > > > > > On Tue, Aug 27, 2019 at 8:53 PM Dave <sn...@gmail.com>
> > > > > > wrote:
> > > > > > > > > > >>
> > > > > > > > > > >> I think that's a great idea and the docs, or a least the
> > > > > > screenshots,
> > > > > > > > > need
> > > > > > > > > > >> update for the new Roller 6 UI. Markdown is better for
> > > this in
> > > > > > so many
> > > > > > > > > > >> ways. AsciiDoc is also a good option but I don't have a
> > > strong
> > > > > > > > > preference
> > > > > > > > > > >> on Markdown vs. AsciiDoc.
> > > > > > > > > > >>
> > > > > > > > > > >> Dave
> > > > > > > > > > >>
> > > > > > > > > > >>
> > > > > > > > > > >> On Tue, Aug 27, 2019 at 10:06 AM Swapnil M Mane <
> > > > > > > > > swapnilmmane@apache.org>
> > > > > > > > > > >> wrote:
> > > > > > > > > > >>
> > > > > > > > > > >>> Hello team,
> > > > > > > > > > >>> During my exploration for documentation, I found the
> > > > > > documentation
> > > > > > > > > > >>> link [1] on Roller home page [2] under the Documentation
> > > > > > section.
> > > > > > > > > > >>> I see, currently, we are storing the documents in odt
> > > format.
> > > > > > > > > > >>>
> > > > > > > > > > >>> I would like to know the thoughts of the community on
> > > moving
> > > > > > the
> > > > > > > > > > >>> documentation from .odt to .md
> > > > > > > > > > >>>
> > > > > > > > > > >>> We will have the following advantage if we use md format
> > > -
> > > > > > > > > > >>>
> > > > > > > > > > >>> 1. Rendering support of md file on GitHub
> > > > > > > > > > >>> The GitHub nicely render the md files, so if the files
> > > in md
> > > > > > format,
> > > > > > > > > > >>> it will be easily rendered on GitHub.
> > > > > > > > > > >>> The odt files don't have any preview on GitHub and it
> > > forces
> > > > > > the user
> > > > > > > > > > >>> to download to view the content. (This is annoying for
> > > the
> > > > > > user and
> > > > > > > > > > >>> developers ;-)
> > > > > > > > > > >>> e.g.
> > > > > > > > > > >>>
> > > > > > > > >
> > > > > >
> > > https://github.com/apache/roller/blob/master/docs/roller-template-guide.odt
> > > > > > > > > > >>>
> > > > > > > > > > >>> 2. Easy to maintain, the md standard is widely accepted
> > > > > > > > > > >>> The md format is widely used and this will open up the
> > > > > > opportunity
> > > > > > > > > for
> > > > > > > > > > >>> new collaborators to participate.
> > > > > > > > > > >>>
> > > > > > > > > > >>> Kindly let me know if I am missing any information or
> > > history
> > > > > > or
> > > > > > > > > > >>> purpose for maintaining our docs in .odt format.
> > > > > > > > > > >>>
> > > > > > > > > > >>> P.S. I see we are also maintaining the pdf version of
> > > odt [3]
> > > > > > in
> > > > > > > > > master
> > > > > > > > > > >>> branch.
> > > > > > > > > > >>> The conversion from md to pdf is also doable.
> > > > > > > > > > >>> IMO, if we move our documents to md version, the pdf
> > > > > > conversation
> > > > > > > > > will
> > > > > > > > > > >>> be no longer required since it will be rendered on GitHub
> > > > > > properly.
> > > > > > > > > > >>> (Still, if I am missing anything, please feel free to
> > > comment
> > > > > > :-)
> > > > > > > > > > >>>
> > > > > > > > > > >>> [1]
> > > https://github.com/apache/roller/tree/roller-5.2.0/docs
> > > > > > > > > > >>> [2] http://roller.apache.org/
> > > > > > > > > > >>> [3] https://github.com/apache/roller/tree/master/docs
> > > > > > > > > > >>>
> > > > > > > > > > >>> Best regards,
> > > > > > > > > > >>> Swapnil M Mane,
> > > > > > > > > > >>> www.apache.org
> > > > > > > > > > >>>
> > > > > > > > > >
> > > > > > > > >
> > > > > >
> > >
Re: Roller Documentation from ODT to md (markdown)
Posted by Dave <sn...@gmail.com>.
Wow! this is a great contribution. Thank you so much for updating the docs
for the new Roller 6 UI and converting them to a source-code control
friendly format. I plan to have a new release candidate ready tomorrow.
Dave
On Sat, May 2, 2020 at 2:01 PM Swapnil M Mane <sw...@apache.org>
wrote:
> Forgot to add the link,
> Here is the exiting ODT version of User Guide, which is converted to
> AsciiDoc
>
> [1]
> https://github.com/apache/roller/blob/master/docs/roller-user-guide.odt
>
> AsciiDoc version -
> https://github.com/apache/roller/blob/master/docs/roller-user-guide.adoc
>
> Best regards,
> Swapnil M Mane,
> www.apache.org
>
> On Sat, May 2, 2020 at 11:23 PM Swapnil M Mane <sw...@apache.org>
> wrote:
> >
> > Hello team,
> > Here is the translation of the 'User Guide' document [1] from ODT to
> AsciiDoc.
> > It can be referred at
> > https://github.com/apache/roller/blob/master/docs/roller-user-guide.adoc
> >
> > This includes the screenshot of our *new* design and theme for Roller UI
> :)
> >
> > With this translation, all our ODT documents are converted to AsciiDoc.
> >
> > Here is the ticket, we used for this translation,
> > https://issues.apache.org/jira/browse/ROL-2151
> > If you found any issue or improvement in this translation, please feel
> > free to report at ROL-2151.
> >
> > Thanks so much, everyone for your support on this.
> >
> > Best regards,
> > Swapnil M Mane,
> > www.apache.org
> >
> > On Mon, Mar 2, 2020 at 10:32 AM Swapnil M Mane <sw...@apache.org>
> wrote:
> > >
> > > Thank you Dave! :)
> > >
> > > Hi Team,
> > > The translation of 'Template Guide' document [1] from ODT to AsciiDoc
> > > is committed in the Roller 'master' branch at following MR
> > > https://github.com/apache/roller/pull/56
> > > and can be referred at
> > >
> https://github.com/apache/roller/blob/master/docs/roller-template-guide.adoc
> > >
> > > Best regards,
> > > Swapnil M Mane,
> > > www.apache.org
> > > On Sun, Mar 1, 2020 at 11:53 PM Dave <sn...@gmail.com> wrote:
> > > >
> > > > Swapnil,
> > > >
> > > > This looks great, and with updated screenshots! Thanks for doing
> this work.
> > > > It looks nicer and is so much better than having to deal with ODT.
> > > >
> > > > Dave
> > > >
> > > > On Sat, Feb 22, 2020 at 8:41 AM Swapnil M Mane <
> swapnilmmane@apache.org>
> > > > wrote:
> > > >
> > > > > Hello team,
> > > > >
> > > > > Here is the translation of 'Template Guide' document [1] from ODT
> to
> > > > > AsciiDoc.
> > > > > It can be referred at
> > > > >
> > > > >
> https://github.com/swapnilmmane/roller/blob/master/docs/roller-template-guide.adoc
> > > > >
> > > > > This time, it was completely manual work, automation didn't worked
> > > > > because it has various tables and other formatting issues.
> > > > >
> > > > > I have done the following changes in the new document:
> > > > > 1.) Updated the images are per our new Roller UI.
> > > > > 2.) Since the UI workflow and options of customizing theme and
> > > > > templated are changed in our new Roller UI, thus updated the
> content
> > > > > as per the new workflow. The updated content can be referred at
> > > > > https://s.apache.org/g0m8y
> > > > >
> > > > > Kindly have a look and help us in reviewing, I am planning to
> commit
> > > > > at the end of next week.
> > > > >
> > > > > [1]
> > > > >
> https://github.com/apache/roller/blob/master/docs/roller-template-guide.odt
> > > > >
> > > > >
> > > > > Best regards,
> > > > > Swapnil M Mane,
> > > > > www.apache.org
> > > > > On Mon, Sep 23, 2019 at 3:27 PM Swapnil M Mane <
> swapnilmmane@apache.org>
> > > > > wrote:
> > > > > >
> > > > > > Thanks Dave, it's automated + manual work :)
> > > > > >
> > > > > > 1. First I convert ODT to md using
> > > > > > https://www.privatedaddy.com/convert_odt_to_md
> > > > > >
> > > > > > 2. Convert md file to as AsciiDoc using Pandoc.
> > > > > >
> > > > > > 3. The above process introduced various special characters,
> remove
> > > > > > images, and some code snippet issues, fix them manually.
> > > > > >
> > > > > > 4. Then, review the existing ODT and new AsciiDoc file line by
> line
> > > > > > and fix the issues.
> > > > > >
> > > > > > Best regards,
> > > > > > Swapnil M Mane,
> > > > > > www.apache.org
> > > > > >
> > > > > > On Sun, Sep 22, 2019 at 12:30 AM Dave <sn...@gmail.com>
> wrote:
> > > > > > >
> > > > > > > Thanks for doing this work, it looks great! Are you using any
> tools to
> > > > > > > automate the conversion?
> > > > > > >
> > > > > > > Dave
> > > > > > >
> > > > > > >
> > > > > > > On Wed, Sep 18, 2019 at 8:29 AM Swapnil M Mane <
> > > > > swapnilmmane@apache.org>
> > > > > > > wrote:
> > > > > > >
> > > > > > > > Hello team,
> > > > > > > >
> > > > > > > > Here comes our first translation from ODT to AsciiDoc.
> > > > > > > > The 'Installation Guide' document [1] is translated to
> AsciiDoc, it
> > > > > > > > can be referred at
> > > > > > > >
> > > > > > > >
> > > > >
> https://github.com/swapnilmmane/roller/blob/master/docs/roller-install-guide.adoc
> > > > > > > >
> > > > > > > > Before committing, I would like to get it reviewed from the
> > > > > community.
> > > > > > > > Please feel free to comment.
> > > > > > > >
> > > > > > > > P.S. I have removed the 'OpenDS project' mention from
> Acknowledgments
> > > > > > > > section since now we have converted the document to AsciiDoc.
> > > > > > > >
> > > > > > > > [1]
> > > > > > > >
> > > > >
> https://github.com/apache/roller/blob/master/docs/roller-install-guide.odt
> > > > > > > >
> > > > > > > >
> > > > > > > > Best regards,
> > > > > > > > Swapnil M Mane,
> > > > > > > > www.apache.org
> > > > > > > >
> > > > > > > > On Thu, Aug 29, 2019 at 5:44 PM Swapnil M Mane <
> > > > > swapnilmmane@apache.org>
> > > > > > > > wrote:
> > > > > > > > >
> > > > > > > > > Thank you Aditya.
> > > > > > > > >
> > > > > > > > > @Team,
> > > > > > > > > Here is the Jira to track the progress of this effort,
> > > > > > > > > https://issues.apache.org/jira/browse/ROL-2151
> > > > > > > > >
> > > > > > > > >
> > > > > > > > > Best regards,
> > > > > > > > > Swapnil M Mane,
> > > > > > > > > www.apache.org
> > > > > > > > >
> > > > > > > > > On Wed, Aug 28, 2019 at 12:50 PM Aditya Sharma <
> > > > > adityasharma@apache.org>
> > > > > > > > wrote:
> > > > > > > > > >
> > > > > > > > > > Big +1 for AsciiDoc
> > > > > > > > > >
> > > > > > > > > > Thanks and regards,
> > > > > > > > > > Aditya Sharma
> > > > > > > > > >
> > > > > > > > > > On Tue, 27 Aug 2019 at 23:36, Swapnil M Mane <
> > > > > swapnilmmane@apache.org>
> > > > > > > > > > wrote:
> > > > > > > > > >
> > > > > > > > > > > Sure Matt, thank you for the kind note.
> > > > > > > > > > > Will surely sync up with you in case of any issue.
> > > > > > > > > > > I also played with Asciidoctor in past, indeed a great
> tool!
> > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > > > > > Best regards,
> > > > > > > > > > > Swapnil M Mane,
> > > > > > > > > > > www.apache.org
> > > > > > > > > > >
> > > > > > > > > > > On Tue, Aug 27, 2019 at 11:16 PM Matt Raible <
> > > > > matt@raibledesigns.com
> > > > > > > > >
> > > > > > > > > > > wrote:
> > > > > > > > > > > >
> > > > > > > > > > > > +1 for AsciiDoc! I have a lot of experience with
> > > > > Asciidoctor, so
> > > > > > > > let me
> > > > > > > > > > > know if you run into issues.
> > > > > > > > > > > >
> > > > > > > > > > > > Cheers,
> > > > > > > > > > > >
> > > > > > > > > > > > Matt
> > > > > > > > > > > >
> > > > > > > > > > > > > On Aug 27, 2019, at 11:06 AM, Swapnil M Mane <
> > > > > > > > swapnilmmane@apache.org>
> > > > > > > > > > > wrote:
> > > > > > > > > > > > >
> > > > > > > > > > > > > Great, thanks Dave.
> > > > > > > > > > > > >
> > > > > > > > > > > > > Thoughts travels, while drafting the mail,
> AsciiDoc was
> > > > > also in
> > > > > > > > my
> > > > > > > > > > > mind.
> > > > > > > > > > > > > And AsciiDoc is also having all the advantages
> mentioned
> > > > > above.
> > > > > > > > > > > > >
> > > > > > > > > > > > > After some more exploration, I am now more
> inclined towards
> > > > > > > > AsciiDoc.
> > > > > > > > > > > > > So, +1 for AsciiDoc.
> > > > > > > > > > > > >
> > > > > > > > > > > > >
> > > > > > > > > > > > > Best regards,
> > > > > > > > > > > > > Swapnil M Mane,
> > > > > > > > > > > > > www.apache.org
> > > > > > > > > > > > >
> > > > > > > > > > > > > On Tue, Aug 27, 2019 at 8:53 PM Dave <
> snoopdave@gmail.com>
> > > > > > > > wrote:
> > > > > > > > > > > > >>
> > > > > > > > > > > > >> I think that's a great idea and the docs, or a
> least the
> > > > > > > > screenshots,
> > > > > > > > > > > need
> > > > > > > > > > > > >> update for the new Roller 6 UI. Markdown is
> better for
> > > > > this in
> > > > > > > > so many
> > > > > > > > > > > > >> ways. AsciiDoc is also a good option but I don't
> have a
> > > > > strong
> > > > > > > > > > > preference
> > > > > > > > > > > > >> on Markdown vs. AsciiDoc.
> > > > > > > > > > > > >>
> > > > > > > > > > > > >> Dave
> > > > > > > > > > > > >>
> > > > > > > > > > > > >>
> > > > > > > > > > > > >> On Tue, Aug 27, 2019 at 10:06 AM Swapnil M Mane <
> > > > > > > > > > > swapnilmmane@apache.org>
> > > > > > > > > > > > >> wrote:
> > > > > > > > > > > > >>
> > > > > > > > > > > > >>> Hello team,
> > > > > > > > > > > > >>> During my exploration for documentation, I found
> the
> > > > > > > > documentation
> > > > > > > > > > > > >>> link [1] on Roller home page [2] under the
> Documentation
> > > > > > > > section.
> > > > > > > > > > > > >>> I see, currently, we are storing the documents
> in odt
> > > > > format.
> > > > > > > > > > > > >>>
> > > > > > > > > > > > >>> I would like to know the thoughts of the
> community on
> > > > > moving
> > > > > > > > the
> > > > > > > > > > > > >>> documentation from .odt to .md
> > > > > > > > > > > > >>>
> > > > > > > > > > > > >>> We will have the following advantage if we use
> md format
> > > > > -
> > > > > > > > > > > > >>>
> > > > > > > > > > > > >>> 1. Rendering support of md file on GitHub
> > > > > > > > > > > > >>> The GitHub nicely render the md files, so if the
> files
> > > > > in md
> > > > > > > > format,
> > > > > > > > > > > > >>> it will be easily rendered on GitHub.
> > > > > > > > > > > > >>> The odt files don't have any preview on GitHub
> and it
> > > > > forces
> > > > > > > > the user
> > > > > > > > > > > > >>> to download to view the content. (This is
> annoying for
> > > > > the
> > > > > > > > user and
> > > > > > > > > > > > >>> developers ;-)
> > > > > > > > > > > > >>> e.g.
> > > > > > > > > > > > >>>
> > > > > > > > > > >
> > > > > > > >
> > > > >
> https://github.com/apache/roller/blob/master/docs/roller-template-guide.odt
> > > > > > > > > > > > >>>
> > > > > > > > > > > > >>> 2. Easy to maintain, the md standard is widely
> accepted
> > > > > > > > > > > > >>> The md format is widely used and this will open
> up the
> > > > > > > > opportunity
> > > > > > > > > > > for
> > > > > > > > > > > > >>> new collaborators to participate.
> > > > > > > > > > > > >>>
> > > > > > > > > > > > >>> Kindly let me know if I am missing any
> information or
> > > > > history
> > > > > > > > or
> > > > > > > > > > > > >>> purpose for maintaining our docs in .odt format.
> > > > > > > > > > > > >>>
> > > > > > > > > > > > >>> P.S. I see we are also maintaining the pdf
> version of
> > > > > odt [3]
> > > > > > > > in
> > > > > > > > > > > master
> > > > > > > > > > > > >>> branch.
> > > > > > > > > > > > >>> The conversion from md to pdf is also doable.
> > > > > > > > > > > > >>> IMO, if we move our documents to md version, the
> pdf
> > > > > > > > conversation
> > > > > > > > > > > will
> > > > > > > > > > > > >>> be no longer required since it will be rendered
> on GitHub
> > > > > > > > properly.
> > > > > > > > > > > > >>> (Still, if I am missing anything, please feel
> free to
> > > > > comment
> > > > > > > > :-)
> > > > > > > > > > > > >>>
> > > > > > > > > > > > >>> [1]
> > > > > https://github.com/apache/roller/tree/roller-5.2.0/docs
> > > > > > > > > > > > >>> [2] http://roller.apache.org/
> > > > > > > > > > > > >>> [3]
> https://github.com/apache/roller/tree/master/docs
> > > > > > > > > > > > >>>
> > > > > > > > > > > > >>> Best regards,
> > > > > > > > > > > > >>> Swapnil M Mane,
> > > > > > > > > > > > >>> www.apache.org
> > > > > > > > > > > > >>>
> > > > > > > > > > > >
> > > > > > > > > > >
> > > > > > > >
> > > > >
>
Re: Roller Documentation from ODT to md (markdown)
Posted by Swapnil M Mane <sw...@apache.org>.
Forgot to add the link,
Here is the exiting ODT version of User Guide, which is converted to AsciiDoc
[1] https://github.com/apache/roller/blob/master/docs/roller-user-guide.odt
AsciiDoc version -
https://github.com/apache/roller/blob/master/docs/roller-user-guide.adoc
Best regards,
Swapnil M Mane,
www.apache.org
On Sat, May 2, 2020 at 11:23 PM Swapnil M Mane <sw...@apache.org> wrote:
>
> Hello team,
> Here is the translation of the 'User Guide' document [1] from ODT to AsciiDoc.
> It can be referred at
> https://github.com/apache/roller/blob/master/docs/roller-user-guide.adoc
>
> This includes the screenshot of our *new* design and theme for Roller UI :)
>
> With this translation, all our ODT documents are converted to AsciiDoc.
>
> Here is the ticket, we used for this translation,
> https://issues.apache.org/jira/browse/ROL-2151
> If you found any issue or improvement in this translation, please feel
> free to report at ROL-2151.
>
> Thanks so much, everyone for your support on this.
>
> Best regards,
> Swapnil M Mane,
> www.apache.org
>
> On Mon, Mar 2, 2020 at 10:32 AM Swapnil M Mane <sw...@apache.org> wrote:
> >
> > Thank you Dave! :)
> >
> > Hi Team,
> > The translation of 'Template Guide' document [1] from ODT to AsciiDoc
> > is committed in the Roller 'master' branch at following MR
> > https://github.com/apache/roller/pull/56
> > and can be referred at
> > https://github.com/apache/roller/blob/master/docs/roller-template-guide.adoc
> >
> > Best regards,
> > Swapnil M Mane,
> > www.apache.org
> > On Sun, Mar 1, 2020 at 11:53 PM Dave <sn...@gmail.com> wrote:
> > >
> > > Swapnil,
> > >
> > > This looks great, and with updated screenshots! Thanks for doing this work.
> > > It looks nicer and is so much better than having to deal with ODT.
> > >
> > > Dave
> > >
> > > On Sat, Feb 22, 2020 at 8:41 AM Swapnil M Mane <sw...@apache.org>
> > > wrote:
> > >
> > > > Hello team,
> > > >
> > > > Here is the translation of 'Template Guide' document [1] from ODT to
> > > > AsciiDoc.
> > > > It can be referred at
> > > >
> > > > https://github.com/swapnilmmane/roller/blob/master/docs/roller-template-guide.adoc
> > > >
> > > > This time, it was completely manual work, automation didn't worked
> > > > because it has various tables and other formatting issues.
> > > >
> > > > I have done the following changes in the new document:
> > > > 1.) Updated the images are per our new Roller UI.
> > > > 2.) Since the UI workflow and options of customizing theme and
> > > > templated are changed in our new Roller UI, thus updated the content
> > > > as per the new workflow. The updated content can be referred at
> > > > https://s.apache.org/g0m8y
> > > >
> > > > Kindly have a look and help us in reviewing, I am planning to commit
> > > > at the end of next week.
> > > >
> > > > [1]
> > > > https://github.com/apache/roller/blob/master/docs/roller-template-guide.odt
> > > >
> > > >
> > > > Best regards,
> > > > Swapnil M Mane,
> > > > www.apache.org
> > > > On Mon, Sep 23, 2019 at 3:27 PM Swapnil M Mane <sw...@apache.org>
> > > > wrote:
> > > > >
> > > > > Thanks Dave, it's automated + manual work :)
> > > > >
> > > > > 1. First I convert ODT to md using
> > > > > https://www.privatedaddy.com/convert_odt_to_md
> > > > >
> > > > > 2. Convert md file to as AsciiDoc using Pandoc.
> > > > >
> > > > > 3. The above process introduced various special characters, remove
> > > > > images, and some code snippet issues, fix them manually.
> > > > >
> > > > > 4. Then, review the existing ODT and new AsciiDoc file line by line
> > > > > and fix the issues.
> > > > >
> > > > > Best regards,
> > > > > Swapnil M Mane,
> > > > > www.apache.org
> > > > >
> > > > > On Sun, Sep 22, 2019 at 12:30 AM Dave <sn...@gmail.com> wrote:
> > > > > >
> > > > > > Thanks for doing this work, it looks great! Are you using any tools to
> > > > > > automate the conversion?
> > > > > >
> > > > > > Dave
> > > > > >
> > > > > >
> > > > > > On Wed, Sep 18, 2019 at 8:29 AM Swapnil M Mane <
> > > > swapnilmmane@apache.org>
> > > > > > wrote:
> > > > > >
> > > > > > > Hello team,
> > > > > > >
> > > > > > > Here comes our first translation from ODT to AsciiDoc.
> > > > > > > The 'Installation Guide' document [1] is translated to AsciiDoc, it
> > > > > > > can be referred at
> > > > > > >
> > > > > > >
> > > > https://github.com/swapnilmmane/roller/blob/master/docs/roller-install-guide.adoc
> > > > > > >
> > > > > > > Before committing, I would like to get it reviewed from the
> > > > community.
> > > > > > > Please feel free to comment.
> > > > > > >
> > > > > > > P.S. I have removed the 'OpenDS project' mention from Acknowledgments
> > > > > > > section since now we have converted the document to AsciiDoc.
> > > > > > >
> > > > > > > [1]
> > > > > > >
> > > > https://github.com/apache/roller/blob/master/docs/roller-install-guide.odt
> > > > > > >
> > > > > > >
> > > > > > > Best regards,
> > > > > > > Swapnil M Mane,
> > > > > > > www.apache.org
> > > > > > >
> > > > > > > On Thu, Aug 29, 2019 at 5:44 PM Swapnil M Mane <
> > > > swapnilmmane@apache.org>
> > > > > > > wrote:
> > > > > > > >
> > > > > > > > Thank you Aditya.
> > > > > > > >
> > > > > > > > @Team,
> > > > > > > > Here is the Jira to track the progress of this effort,
> > > > > > > > https://issues.apache.org/jira/browse/ROL-2151
> > > > > > > >
> > > > > > > >
> > > > > > > > Best regards,
> > > > > > > > Swapnil M Mane,
> > > > > > > > www.apache.org
> > > > > > > >
> > > > > > > > On Wed, Aug 28, 2019 at 12:50 PM Aditya Sharma <
> > > > adityasharma@apache.org>
> > > > > > > wrote:
> > > > > > > > >
> > > > > > > > > Big +1 for AsciiDoc
> > > > > > > > >
> > > > > > > > > Thanks and regards,
> > > > > > > > > Aditya Sharma
> > > > > > > > >
> > > > > > > > > On Tue, 27 Aug 2019 at 23:36, Swapnil M Mane <
> > > > swapnilmmane@apache.org>
> > > > > > > > > wrote:
> > > > > > > > >
> > > > > > > > > > Sure Matt, thank you for the kind note.
> > > > > > > > > > Will surely sync up with you in case of any issue.
> > > > > > > > > > I also played with Asciidoctor in past, indeed a great tool!
> > > > > > > > > >
> > > > > > > > > >
> > > > > > > > > > Best regards,
> > > > > > > > > > Swapnil M Mane,
> > > > > > > > > > www.apache.org
> > > > > > > > > >
> > > > > > > > > > On Tue, Aug 27, 2019 at 11:16 PM Matt Raible <
> > > > matt@raibledesigns.com
> > > > > > > >
> > > > > > > > > > wrote:
> > > > > > > > > > >
> > > > > > > > > > > +1 for AsciiDoc! I have a lot of experience with
> > > > Asciidoctor, so
> > > > > > > let me
> > > > > > > > > > know if you run into issues.
> > > > > > > > > > >
> > > > > > > > > > > Cheers,
> > > > > > > > > > >
> > > > > > > > > > > Matt
> > > > > > > > > > >
> > > > > > > > > > > > On Aug 27, 2019, at 11:06 AM, Swapnil M Mane <
> > > > > > > swapnilmmane@apache.org>
> > > > > > > > > > wrote:
> > > > > > > > > > > >
> > > > > > > > > > > > Great, thanks Dave.
> > > > > > > > > > > >
> > > > > > > > > > > > Thoughts travels, while drafting the mail, AsciiDoc was
> > > > also in
> > > > > > > my
> > > > > > > > > > mind.
> > > > > > > > > > > > And AsciiDoc is also having all the advantages mentioned
> > > > above.
> > > > > > > > > > > >
> > > > > > > > > > > > After some more exploration, I am now more inclined towards
> > > > > > > AsciiDoc.
> > > > > > > > > > > > So, +1 for AsciiDoc.
> > > > > > > > > > > >
> > > > > > > > > > > >
> > > > > > > > > > > > Best regards,
> > > > > > > > > > > > Swapnil M Mane,
> > > > > > > > > > > > www.apache.org
> > > > > > > > > > > >
> > > > > > > > > > > > On Tue, Aug 27, 2019 at 8:53 PM Dave <sn...@gmail.com>
> > > > > > > wrote:
> > > > > > > > > > > >>
> > > > > > > > > > > >> I think that's a great idea and the docs, or a least the
> > > > > > > screenshots,
> > > > > > > > > > need
> > > > > > > > > > > >> update for the new Roller 6 UI. Markdown is better for
> > > > this in
> > > > > > > so many
> > > > > > > > > > > >> ways. AsciiDoc is also a good option but I don't have a
> > > > strong
> > > > > > > > > > preference
> > > > > > > > > > > >> on Markdown vs. AsciiDoc.
> > > > > > > > > > > >>
> > > > > > > > > > > >> Dave
> > > > > > > > > > > >>
> > > > > > > > > > > >>
> > > > > > > > > > > >> On Tue, Aug 27, 2019 at 10:06 AM Swapnil M Mane <
> > > > > > > > > > swapnilmmane@apache.org>
> > > > > > > > > > > >> wrote:
> > > > > > > > > > > >>
> > > > > > > > > > > >>> Hello team,
> > > > > > > > > > > >>> During my exploration for documentation, I found the
> > > > > > > documentation
> > > > > > > > > > > >>> link [1] on Roller home page [2] under the Documentation
> > > > > > > section.
> > > > > > > > > > > >>> I see, currently, we are storing the documents in odt
> > > > format.
> > > > > > > > > > > >>>
> > > > > > > > > > > >>> I would like to know the thoughts of the community on
> > > > moving
> > > > > > > the
> > > > > > > > > > > >>> documentation from .odt to .md
> > > > > > > > > > > >>>
> > > > > > > > > > > >>> We will have the following advantage if we use md format
> > > > -
> > > > > > > > > > > >>>
> > > > > > > > > > > >>> 1. Rendering support of md file on GitHub
> > > > > > > > > > > >>> The GitHub nicely render the md files, so if the files
> > > > in md
> > > > > > > format,
> > > > > > > > > > > >>> it will be easily rendered on GitHub.
> > > > > > > > > > > >>> The odt files don't have any preview on GitHub and it
> > > > forces
> > > > > > > the user
> > > > > > > > > > > >>> to download to view the content. (This is annoying for
> > > > the
> > > > > > > user and
> > > > > > > > > > > >>> developers ;-)
> > > > > > > > > > > >>> e.g.
> > > > > > > > > > > >>>
> > > > > > > > > >
> > > > > > >
> > > > https://github.com/apache/roller/blob/master/docs/roller-template-guide.odt
> > > > > > > > > > > >>>
> > > > > > > > > > > >>> 2. Easy to maintain, the md standard is widely accepted
> > > > > > > > > > > >>> The md format is widely used and this will open up the
> > > > > > > opportunity
> > > > > > > > > > for
> > > > > > > > > > > >>> new collaborators to participate.
> > > > > > > > > > > >>>
> > > > > > > > > > > >>> Kindly let me know if I am missing any information or
> > > > history
> > > > > > > or
> > > > > > > > > > > >>> purpose for maintaining our docs in .odt format.
> > > > > > > > > > > >>>
> > > > > > > > > > > >>> P.S. I see we are also maintaining the pdf version of
> > > > odt [3]
> > > > > > > in
> > > > > > > > > > master
> > > > > > > > > > > >>> branch.
> > > > > > > > > > > >>> The conversion from md to pdf is also doable.
> > > > > > > > > > > >>> IMO, if we move our documents to md version, the pdf
> > > > > > > conversation
> > > > > > > > > > will
> > > > > > > > > > > >>> be no longer required since it will be rendered on GitHub
> > > > > > > properly.
> > > > > > > > > > > >>> (Still, if I am missing anything, please feel free to
> > > > comment
> > > > > > > :-)
> > > > > > > > > > > >>>
> > > > > > > > > > > >>> [1]
> > > > https://github.com/apache/roller/tree/roller-5.2.0/docs
> > > > > > > > > > > >>> [2] http://roller.apache.org/
> > > > > > > > > > > >>> [3] https://github.com/apache/roller/tree/master/docs
> > > > > > > > > > > >>>
> > > > > > > > > > > >>> Best regards,
> > > > > > > > > > > >>> Swapnil M Mane,
> > > > > > > > > > > >>> www.apache.org
> > > > > > > > > > > >>>
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > >
> > > >