[Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

Hello Folks,

We've had this discussion multiple times in the past, but I think I
have a more concrete idea this time for solving this problem. In the
past few weeks we've been working internally in Pythys to figure out
the best way to write and distribute documentation, and I think most
of that is applicable to OFBiz.

In a nutshell, here is the idea (practically) for how to proceed:

- The documentation language to use is Asciidoc
- The documentation tool is Asciidoctor
- Publishing happens through Gradle using the asciidoctor gradle
plugin (not the OFBiz framework or anything else).
- The only place where we write documentation is inside the code base
- Every component contains its own documentation
- General documentation goes to either a standalone directory or a
generic component like common or base
- As much as possible, documentation files are small and focused on
one topic. And then other longer documents are constructed from these
snippets of documentation.
- We publish to all formats including PDF for users, or HTML for
embedded help and wiki pages. So OFBiz does not parse docbook for its
help system, instead it just renders generated HTML.

As I've worked extensively with Asciidoc I find it easy to pickup
(like markdown) but also modular (like docbook and dita). It's also
neat that you can sprinkle variables all around in your document so
that update is no longer a painful grepping process.

Would love to hear your thoughts on this.

Cheers,

Taher Alkhateeb

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

Thank you folks for your feedback. Based on everyone's input, I think
perhaps a good way to move forward is by creating a JIRA and making a
patch for a PoC.

I think altering the OFBiz help system for now might be a bigger task,
so for a start, I think I will write some documentation in multiple
places and then let gradle consolidate that into an output manual.
Then, based on feedback from you we decide on the next step.

So I will proceed with creating a JIRA for an initial PoC. Again,
thank you for your thoughts, all constructive and valuable.

On Wed, Oct 18, 2017 at 11:47 AM, Jacques Le Roux
<ja...@les7arts.com> wrote:
> Hi Sharan,
>
> Yes I'm pretty sure we will still need the wiki. For technical points which
> don't specially fit in source and also some kind of user documentation, but
> the less the better.
>
> Jacques
>
>
> Le 18/10/2017 à 10:28, Sharan Foga a écrit :
>>
>> Hi
>>
>> I would say the first and easier focus is to complete the online help.
>> Telling people how to use the screens and applications is a basic
>> requirement that we haven't fulfilled for OFBiz yet.  Once we have that then
>> we can see how it can be expanded to incorporate more general details. I
>> think the issue we have had over the years is that OFBiz is so big that it's
>> difficult to know where to start.
>>
>> At least if we can give people information about the application they are
>> using, and how to use the screens, then that will give them enough to get
>> going. For content we could review the existing help that we have and update
>> it into a standard format or template so that it is consistent.
>>
>> We may also find that we still need the wiki for something so let's see
>> what happens
>>
>> Thanks
>> Sharan
>>
>> On 2017-10-17 13:21, Jacques Le Roux <ja...@les7arts.com> wrote:
>>>
>>> Yes thanks Taher to have picked this again,
>>>
>>> I agree with all what have been said so far.
>>>
>>> You know my preference for asscidoc and asciidoctor. Using the
>>> asciidoctor Gradle plugin seems logical to me.
>>>
>>> I'm all for having all the documentation inside the source. I had even
>>> created a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423
>>>
>>> Questions:
>>>
>>>   1. Should we continue to provide an online help? Would we reuse/upgrade
>>> the current one?
>>>   2. Where to put the common documentation? In common or commonext
>>> component or in a new documentation folder? Later seems easier for newbies,
>>> name
>>>      says all.
>>>   3. I use pandoc to create (from some .md files) md.html files in
>>> tools\wiki-files imported in wiki pages. I regularly use a .bat for that.
>>> Would we
>>>      replace also our current .md files?
>>>
>>> Jacques
>>>
>>>
>>> Le 17/10/2017 à 11:25, Michael Brohl a écrit :
>>>
>>>> Big +1 for this initiative!
>>>>
>>>> I have not much to add to Taher's proposal and Sharan's viewpoint.
>>>>
>>>> I assume that we can use any Asciidoc editor and need not to use
>>>> Asciidoctor?
>>>>
>>>> I think we have to decide what we will do with our Wiki based
>>>> documentation then. If we have up-to-date documentation in the components
>>>> and can
>>>> generate up-to-date documentation every night, pretty much of the Wiki
>>>> documentation would be obsolete. A simple link to the generated
>>>> documentation
>>>> would be enough, right?
>>>>
>>>> For new code in framework and plugins, I would strongly recommend to
>>>> have mandatory documentation as part of the first commit to the codebase to
>>>> assure a good initial start.
>>>>
>>>> I think we should just start with a proof-of-concept by moving some
>>>> small part of the documentation to Asciidoc and into the codebase.
>>>>
>>>> Would be a great starting point for new contributors also.
>>>>
>>>> Best regards,
>>>>
>>>> Michael
>>>>
>>>>
>>>> Am 17.10.17 um 10:30 schrieb Sharan Foga:
>>>>>
>>>>> Hi Taher
>>>>>
>>>>> It's great that this conversation has started again. It would be great
>>>>> to actually start to do something about the integrated help system within
>>>>> OFBiz itself. We have found limitations with the docbook implementation
>>>>> we have, so now have a better idea of what we want to achieve.
>>>>>
>>>>> In the past we've talked a lot about DITA but to me it seemed a lot
>>>>> more complex to understand, structure and generally get started. I've
>>>>> briefly
>>>>> played about with Ascidoc and it seems pretty simple enough to get the
>>>>> hang of and that to me is an important thing. I also like the idea of being
>>>>> able to render multiple formats (and it would be good to make them look
>>>>> nicer and easier to read).
>>>>>
>>>>> Getting a good and functioning help framework into our codebase is long
>>>>> overdue and I'm sure will add some great benefits and also encourage
>>>>> documentation contributions from our community.
>>>>>
>>>>> Big +1 from me!
>>>>>
>>>>> Thanks
>>>>> Sharan
>>>>>
>>>>>
>>>>> On 17/10/17 10:01, Taher Alkhateeb wrote:
>>>>>>
>>>>>> Hello Folks,
>>>>>>
>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>> the best way to write and distribute documentation, and I think most
>>>>>> of that is applicable to OFBiz.
>>>>>>
>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>
>>>>>> - The documentation language to use is Asciidoc
>>>>>> - The documentation tool is Asciidoctor
>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>> - The only place where we write documentation is inside the code base
>>>>>> - Every component contains its own documentation
>>>>>> - General documentation goes to either a standalone directory or a
>>>>>> generic component like common or base
>>>>>> - As much as possible, documentation files are small and focused on
>>>>>> one topic. And then other longer documents are constructed from these
>>>>>> snippets of documentation.
>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>> help system, instead it just renders generated HTML.
>>>>>>
>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>> that update is no longer a painful grepping process.
>>>>>>
>>>>>> Would love to hear your thoughts on this.
>>>>>>
>>>>>> Cheers,
>>>>>>
>>>>>> Taher Alkhateeb
>>>>>
>>>>>
>>>>
>>>
>

Re: [Discussion] documentation framework for OFBiz

[Jacques Le Roux <ja...@les7arts.com>]

Hi Sharan,

Yes I'm pretty sure we will still need the wiki. For technical points which don't specially fit in source and also some kind of user documentation, 
but the less the better.

Jacques


Le 18/10/2017 à 10:28, Sharan Foga a écrit :
> Hi
>
> I would say the first and easier focus is to complete the online help. Telling people how to use the screens and applications is a basic requirement that we haven't fulfilled for OFBiz yet.  Once we have that then we can see how it can be expanded to incorporate more general details. I think the issue we have had over the years is that OFBiz is so big that it's difficult to know where to start.
>
> At least if we can give people information about the application they are using, and how to use the screens, then that will give them enough to get going. For content we could review the existing help that we have and update it into a standard format or template so that it is consistent.
>
> We may also find that we still need the wiki for something so let's see what happens
>
> Thanks
> Sharan
>
> On 2017-10-17 13:21, Jacques Le Roux <ja...@les7arts.com> wrote:
>> Yes thanks Taher to have picked this again,
>>
>> I agree with all what have been said so far.
>>
>> You know my preference for asscidoc and asciidoctor. Using the asciidoctor Gradle plugin seems logical to me.
>>
>> I'm all for having all the documentation inside the source. I had even created a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423
>>
>> Questions:
>>
>>   1. Should we continue to provide an online help? Would we reuse/upgrade the current one?
>>   2. Where to put the common documentation? In common or commonext component or in a new documentation folder? Later seems easier for newbies, name
>>      says all.
>>   3. I use pandoc to create (from some .md files) md.html files in tools\wiki-files imported in wiki pages. I regularly use a .bat for that. Would we
>>      replace also our current .md files?
>>
>> Jacques
>>
>>
>> Le 17/10/2017 à 11:25, Michael Brohl a écrit :
>>> Big +1 for this initiative!
>>>
>>> I have not much to add to Taher's proposal and Sharan's viewpoint.
>>>
>>> I assume that we can use any Asciidoc editor and need not to use Asciidoctor?
>>>
>>> I think we have to decide what we will do with our Wiki based documentation then. If we have up-to-date documentation in the components and can
>>> generate up-to-date documentation every night, pretty much of the Wiki documentation would be obsolete. A simple link to the generated documentation
>>> would be enough, right?
>>>
>>> For new code in framework and plugins, I would strongly recommend to have mandatory documentation as part of the first commit to the codebase to
>>> assure a good initial start.
>>>
>>> I think we should just start with a proof-of-concept by moving some small part of the documentation to Asciidoc and into the codebase.
>>>
>>> Would be a great starting point for new contributors also.
>>>
>>> Best regards,
>>>
>>> Michael
>>>
>>>
>>> Am 17.10.17 um 10:30 schrieb Sharan Foga:
>>>> Hi Taher
>>>>
>>>> It's great that this conversation has started again. It would be great to actually start to do something about the integrated help system within
>>>> OFBiz itself. We have found limitations with the docbook implementation we have, so now have a better idea of what we want to achieve.
>>>>
>>>> In the past we've talked a lot about DITA but to me it seemed a lot more complex to understand, structure and generally get started. I've briefly
>>>> played about with Ascidoc and it seems pretty simple enough to get the hang of and that to me is an important thing. I also like the idea of being
>>>> able to render multiple formats (and it would be good to make them look nicer and easier to read).
>>>>
>>>> Getting a good and functioning help framework into our codebase is long overdue and I'm sure will add some great benefits and also encourage
>>>> documentation contributions from our community.
>>>>
>>>> Big +1 from me!
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>>
>>>> On 17/10/17 10:01, Taher Alkhateeb wrote:
>>>>> Hello Folks,
>>>>>
>>>>> We've had this discussion multiple times in the past, but I think I
>>>>> have a more concrete idea this time for solving this problem. In the
>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>> the best way to write and distribute documentation, and I think most
>>>>> of that is applicable to OFBiz.
>>>>>
>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>
>>>>> - The documentation language to use is Asciidoc
>>>>> - The documentation tool is Asciidoctor
>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>> plugin (not the OFBiz framework or anything else).
>>>>> - The only place where we write documentation is inside the code base
>>>>> - Every component contains its own documentation
>>>>> - General documentation goes to either a standalone directory or a
>>>>> generic component like common or base
>>>>> - As much as possible, documentation files are small and focused on
>>>>> one topic. And then other longer documents are constructed from these
>>>>> snippets of documentation.
>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>> help system, instead it just renders generated HTML.
>>>>>
>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>> neat that you can sprinkle variables all around in your document so
>>>>> that update is no longer a painful grepping process.
>>>>>
>>>>> Would love to hear your thoughts on this.
>>>>>
>>>>> Cheers,
>>>>>
>>>>> Taher Alkhateeb
>>>>
>>>
>>

Re: [Discussion] documentation framework for OFBiz

[Sharan Foga <sh...@apache.org>]

Hi 

I would say the first and easier focus is to complete the online help. Telling people how to use the screens and applications is a basic requirement that we haven't fulfilled for OFBiz yet.  Once we have that then we can see how it can be expanded to incorporate more general details. I think the issue we have had over the years is that OFBiz is so big that it's difficult to know where to start.

At least if we can give people information about the application they are using, and how to use the screens, then that will give them enough to get going. For content we could review the existing help that we have and update it into a standard format or template so that it is consistent. 

We may also find that we still need the wiki for something so let's see what happens

Thanks
Sharan

On 2017-10-17 13:21, Jacques Le Roux <ja...@les7arts.com> wrote: 
> Yes thanks Taher to have picked this again,
> 
> I agree with all what have been said so far.
> 
> You know my preference for asscidoc and asciidoctor. Using the asciidoctor Gradle plugin seems logical to me.
> 
> I'm all for having all the documentation inside the source. I had even created a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423
> 
> Questions:
> 
>  1. Should we continue to provide an online help? Would we reuse/upgrade the current one?
>  2. Where to put the common documentation? In common or commonext component or in a new documentation folder? Later seems easier for newbies, name
>     says all.
>  3. I use pandoc to create (from some .md files) md.html files in tools\wiki-files imported in wiki pages. I regularly use a .bat for that. Would we
>     replace also our current .md files?
> 
> Jacques
> 
> 
> Le 17/10/2017 à 11:25, Michael Brohl a écrit :
> > Big +1 for this initiative!
> >
> > I have not much to add to Taher's proposal and Sharan's viewpoint.
> >
> > I assume that we can use any Asciidoc editor and need not to use Asciidoctor?
> >
> > I think we have to decide what we will do with our Wiki based documentation then. If we have up-to-date documentation in the components and can 
> > generate up-to-date documentation every night, pretty much of the Wiki documentation would be obsolete. A simple link to the generated documentation 
> > would be enough, right?
> >
> > For new code in framework and plugins, I would strongly recommend to have mandatory documentation as part of the first commit to the codebase to 
> > assure a good initial start.
> >
> > I think we should just start with a proof-of-concept by moving some small part of the documentation to Asciidoc and into the codebase.
> >
> > Would be a great starting point for new contributors also.
> >
> > Best regards,
> >
> > Michael
> >
> >
> > Am 17.10.17 um 10:30 schrieb Sharan Foga:
> >> Hi Taher
> >>
> >> It's great that this conversation has started again. It would be great to actually start to do something about the integrated help system within 
> >> OFBiz itself. We have found limitations with the docbook implementation we have, so now have a better idea of what we want to achieve.
> >>
> >> In the past we've talked a lot about DITA but to me it seemed a lot more complex to understand, structure and generally get started. I've briefly 
> >> played about with Ascidoc and it seems pretty simple enough to get the hang of and that to me is an important thing. I also like the idea of being 
> >> able to render multiple formats (and it would be good to make them look nicer and easier to read).
> >>
> >> Getting a good and functioning help framework into our codebase is long overdue and I'm sure will add some great benefits and also encourage 
> >> documentation contributions from our community.
> >>
> >> Big +1 from me!
> >>
> >> Thanks
> >> Sharan
> >>
> >>
> >> On 17/10/17 10:01, Taher Alkhateeb wrote:
> >>> Hello Folks,
> >>>
> >>> We've had this discussion multiple times in the past, but I think I
> >>> have a more concrete idea this time for solving this problem. In the
> >>> past few weeks we've been working internally in Pythys to figure out
> >>> the best way to write and distribute documentation, and I think most
> >>> of that is applicable to OFBiz.
> >>>
> >>> In a nutshell, here is the idea (practically) for how to proceed:
> >>>
> >>> - The documentation language to use is Asciidoc
> >>> - The documentation tool is Asciidoctor
> >>> - Publishing happens through Gradle using the asciidoctor gradle
> >>> plugin (not the OFBiz framework or anything else).
> >>> - The only place where we write documentation is inside the code base
> >>> - Every component contains its own documentation
> >>> - General documentation goes to either a standalone directory or a
> >>> generic component like common or base
> >>> - As much as possible, documentation files are small and focused on
> >>> one topic. And then other longer documents are constructed from these
> >>> snippets of documentation.
> >>> - We publish to all formats including PDF for users, or HTML for
> >>> embedded help and wiki pages. So OFBiz does not parse docbook for its
> >>> help system, instead it just renders generated HTML.
> >>>
> >>> As I've worked extensively with Asciidoc I find it easy to pickup
> >>> (like markdown) but also modular (like docbook and dita). It's also
> >>> neat that you can sprinkle variables all around in your document so
> >>> that update is no longer a painful grepping process.
> >>>
> >>> Would love to hear your thoughts on this.
> >>>
> >>> Cheers,
> >>>
> >>> Taher Alkhateeb
> >>
> >>
> >
> >
> 
> 

Re: [Discussion] documentation framework for OFBiz

[Jacques Le Roux <ja...@les7arts.com>]

Yes thanks Taher to have picked this again,

I agree with all what have been said so far.

You know my preference for asscidoc and asciidoctor. Using the asciidoctor Gradle plugin seems logical to me.

I'm all for having all the documentation inside the source. I had even created a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423

Questions:

 1. Should we continue to provide an online help? Would we reuse/upgrade the current one?
 2. Where to put the common documentation? In common or commonext component or in a new documentation folder? Later seems easier for newbies, name
    says all.
 3. I use pandoc to create (from some .md files) md.html files in tools\wiki-files imported in wiki pages. I regularly use a .bat for that. Would we
    replace also our current .md files?

Jacques


Le 17/10/2017 à 11:25, Michael Brohl a écrit :
> Big +1 for this initiative!
>
> I have not much to add to Taher's proposal and Sharan's viewpoint.
>
> I assume that we can use any Asciidoc editor and need not to use Asciidoctor?
>
> I think we have to decide what we will do with our Wiki based documentation then. If we have up-to-date documentation in the components and can 
> generate up-to-date documentation every night, pretty much of the Wiki documentation would be obsolete. A simple link to the generated documentation 
> would be enough, right?
>
> For new code in framework and plugins, I would strongly recommend to have mandatory documentation as part of the first commit to the codebase to 
> assure a good initial start.
>
> I think we should just start with a proof-of-concept by moving some small part of the documentation to Asciidoc and into the codebase.
>
> Would be a great starting point for new contributors also.
>
> Best regards,
>
> Michael
>
>
> Am 17.10.17 um 10:30 schrieb Sharan Foga:
>> Hi Taher
>>
>> It's great that this conversation has started again. It would be great to actually start to do something about the integrated help system within 
>> OFBiz itself. We have found limitations with the docbook implementation we have, so now have a better idea of what we want to achieve.
>>
>> In the past we've talked a lot about DITA but to me it seemed a lot more complex to understand, structure and generally get started. I've briefly 
>> played about with Ascidoc and it seems pretty simple enough to get the hang of and that to me is an important thing. I also like the idea of being 
>> able to render multiple formats (and it would be good to make them look nicer and easier to read).
>>
>> Getting a good and functioning help framework into our codebase is long overdue and I'm sure will add some great benefits and also encourage 
>> documentation contributions from our community.
>>
>> Big +1 from me!
>>
>> Thanks
>> Sharan
>>
>>
>> On 17/10/17 10:01, Taher Alkhateeb wrote:
>>> Hello Folks,
>>>
>>> We've had this discussion multiple times in the past, but I think I
>>> have a more concrete idea this time for solving this problem. In the
>>> past few weeks we've been working internally in Pythys to figure out
>>> the best way to write and distribute documentation, and I think most
>>> of that is applicable to OFBiz.
>>>
>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>
>>> - The documentation language to use is Asciidoc
>>> - The documentation tool is Asciidoctor
>>> - Publishing happens through Gradle using the asciidoctor gradle
>>> plugin (not the OFBiz framework or anything else).
>>> - The only place where we write documentation is inside the code base
>>> - Every component contains its own documentation
>>> - General documentation goes to either a standalone directory or a
>>> generic component like common or base
>>> - As much as possible, documentation files are small and focused on
>>> one topic. And then other longer documents are constructed from these
>>> snippets of documentation.
>>> - We publish to all formats including PDF for users, or HTML for
>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>> help system, instead it just renders generated HTML.
>>>
>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>> (like markdown) but also modular (like docbook and dita). It's also
>>> neat that you can sprinkle variables all around in your document so
>>> that update is no longer a painful grepping process.
>>>
>>> Would love to hear your thoughts on this.
>>>
>>> Cheers,
>>>
>>> Taher Alkhateeb
>>
>>
>
>

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

Hi Sharan,

As I was explaining to Jacques, there is no tool selection issue. Pandoc
cannot handle asciidoc and therefore the best viable choice is asciidoctor.
What is stopping us right now is my delay in implementing the feature ( I
am about half way through in OFBIZ-9873 to tackle the PoC ).

On Nov 8, 2017 1:21 PM, "Sharan Foga" <sh...@gmail.com> wrote:

Hi All

At the Open Source Summit in Prague a couple of weeks ago I attended quite
a few documentation related talks and also interviewed one of the
presenters (Robert Kratky from Red Hat) for FeatherCast. He did a talk
about converting legacy docs into more user story based content, so bit
like what we need to do. Anyway his recommendation was Asciidoc and he also
had some links to resources that could help in our documentation journey.

If the tool selection is actually stopping us from moving onto the next
step then let's present the proposal options (e.g Asciidoc, Pandoc etc) and
ask the community to select their preference..

Thanks
Sharan



On 08/11/17 10:33, Taher Alkhateeb wrote:

> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>
> On Nov 8, 2017 12:29 PM, "Jacques Le Roux" <ja...@les7arts.com>
> wrote:
>
> Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :
>
> On 17 October 2017 at 20:25, Michael Brohl <mi...@ecomify.de>
>> wrote:
>>
>>
>> I assume that we can use any Asciidoc editor and need not to use
>>
>>> Asciidoctor?
>>>
>>> Hi Michael,
>>>
>> Asciidoctor is not an editor, it's a text processor that can convert
>> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to
>> Pandoc
>> (https://pandoc.org/).
>>
>> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
>> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
>> for IntelliJ IDEA. Your tastes may vary.
>>
>> Cheers
>>
>> Paul Foxworthy
>>
>> Hi Paul,
>>
> Do you know if there are there good reasons to favor Asciidoctor over
> Pandoc?
> I'm more in favour of the later because now I know it (thanks to you :))
> and especially because it offers so much possibilities, see graph here
> https://pandoc.org/
> You never know what you will need one day...
>
> Jacques
>
>

Re: [Discussion] documentation framework for OFBiz

[Sharan Foga <sh...@gmail.com>]

Hi All

At the Open Source Summit in Prague a couple of weeks ago I attended 
quite a few documentation related talks and also interviewed one of the 
presenters (Robert Kratky from Red Hat) for FeatherCast. He did a talk 
about converting legacy docs into more user story based content, so bit 
like what we need to do. Anyway his recommendation was Asciidoc and he 
also had some links to resources that could help in our documentation 
journey.

If the tool selection is actually stopping us from moving onto the next 
step then let's present the proposal options (e.g Asciidoc, Pandoc etc) 
and ask the community to select their preference..

Thanks
Sharan


On 08/11/17 10:33, Taher Alkhateeb wrote:
> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>
> On Nov 8, 2017 12:29 PM, "Jacques Le Roux" <ja...@les7arts.com>
> wrote:
>
> Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :
>
>> On 17 October 2017 at 20:25, Michael Brohl <mi...@ecomify.de>
>> wrote:
>>
>>
>> I assume that we can use any Asciidoc editor and need not to use
>>> Asciidoctor?
>>>
>>> Hi Michael,
>> Asciidoctor is not an editor, it's a text processor that can convert
>> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
>> (https://pandoc.org/).
>>
>> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
>> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
>> for IntelliJ IDEA. Your tastes may vary.
>>
>> Cheers
>>
>> Paul Foxworthy
>>
>> Hi Paul,
> Do you know if there are there good reasons to favor Asciidoctor over
> Pandoc?
> I'm more in favour of the later because now I know it (thanks to you :))
> and especially because it offers so much possibilities, see graph here
> https://pandoc.org/
> You never know what you will need one day...
>
> Jacques
>

Re: [Discussion] documentation framework for OFBiz

[Jacques Le Roux <ja...@les7arts.com>]

Ha thanks Taher, this answer to Michael's question: we indeed need Asciidoctor if we want to transform from Asciidoc to other formats. Then Pandoc can 
possibly be used for more possibilities

Jacques


Le 08/11/2017 à 10:33, Taher Alkhateeb a écrit :
> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>
> On Nov 8, 2017 12:29 PM, "Jacques Le Roux" <ja...@les7arts.com>
> wrote:
>
> Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :
>
>> On 17 October 2017 at 20:25, Michael Brohl <mi...@ecomify.de>
>> wrote:
>>
>>
>> I assume that we can use any Asciidoc editor and need not to use
>>> Asciidoctor?
>>>
>>> Hi Michael,
>> Asciidoctor is not an editor, it's a text processor that can convert
>> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
>> (https://pandoc.org/).
>>
>> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
>> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
>> for IntelliJ IDEA. Your tastes may vary.
>>
>> Cheers
>>
>> Paul Foxworthy
>>
>> Hi Paul,
> Do you know if there are there good reasons to favor Asciidoctor over
> Pandoc?
> I'm more in favour of the later because now I know it (thanks to you :))
> and especially because it offers so much possibilities, see graph here
> https://pandoc.org/
> You never know what you will need one day...
>
> Jacques
>

Re: [Discussion] documentation framework for OFBiz

[Paul Foxworthy <pa...@cohsoft.com.au>]

On 9 November 2017 at 18:26, Taher Alkhateeb <sl...@gmail.com>
wrote:


> Anyway I don't see a reason so far to use pandoc to publish to pdf.
> Asciidoctor can publish to html, docbook, pdf and others.


Thanks Taher. That's fine by me.

Cheers

Paul Foxworthy

-- 
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Australia

Phone: +61 3 9585 6788
Web: http://www.coherentsoftware.com.au/
Email: info@coherentsoftware.com.au

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

Hi Paul,

First regarding your comment about pandoc, essentially pandoc is a set of
readers and writers. Each markup language needs a reader to convert from
and a writer to convert to. Asciidoc is missing a reader implementation. I
hope someone would implement it eventually.

Anyway I don't see a reason so far to use pandoc to publish to pdf.
Asciidoctor can publish to html, docbook, pdf and others. I like pandoc, it
is a swiss army knife kind of tool for conversion and written in haskell
(fantastic). However like a swiss army knife, it is not specialized like a
native tool designed for the job. So the time to use pandoc might be if
we're stuck or have some limitation with asciidoctor.

On Nov 9, 2017 2:28 AM, "Paul Foxworthy" <pa...@cohsoft.com.au> wrote:

On 8 November 2017 at 20:33, Taher Alkhateeb <sl...@gmail.com>
 wrote:

> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>

Thanks Taher,

My impression was pandoc can read just about any structured input. It's
curious AsciiDoc isn't there.

So for HTML it's

AsciiDoc -- (asciidoctor) --> HTML

and for PDF it's

AsciiDoc -- (asciidoctor) --> DocBook XML -- (pandoc) --> PDF

That sound right?

Cheers

Paul

--
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Australia

Phone: +61 3 9585 6788
Web: http://www.coherentsoftware.com.au/
Email: info@coherentsoftware.com.au

Re: [Discussion] documentation framework for OFBiz

[Paul Foxworthy <pa...@cohsoft.com.au>]

On 8 November 2017 at 20:33, Taher Alkhateeb <sl...@gmail.com>
 wrote:

> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>

Thanks Taher,

My impression was pandoc can read just about any structured input. It's
curious AsciiDoc isn't there.

So for HTML it's

AsciiDoc -- (asciidoctor) --> HTML

and for PDF it's

AsciiDoc -- (asciidoctor) --> DocBook XML -- (pandoc) --> PDF

That sound right?

Cheers

Paul

-- 
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Australia

Phone: +61 3 9585 6788
Web: http://www.coherentsoftware.com.au/
Email: info@coherentsoftware.com.au

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

If you check the link you sent, you will notice that asciidoc is not an
input format in pandoc, but rather an ouput format.

On Nov 8, 2017 12:29 PM, "Jacques Le Roux" <ja...@les7arts.com>
wrote:

Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :

> On 17 October 2017 at 20:25, Michael Brohl <mi...@ecomify.de>
> wrote:
>
>
> I assume that we can use any Asciidoc editor and need not to use
>> Asciidoctor?
>>
>> Hi Michael,
>
> Asciidoctor is not an editor, it's a text processor that can convert
> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
> (https://pandoc.org/).
>
> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
> for IntelliJ IDEA. Your tastes may vary.
>
> Cheers
>
> Paul Foxworthy
>
> Hi Paul,

Do you know if there are there good reasons to favor Asciidoctor over
Pandoc?
I'm more in favour of the later because now I know it (thanks to you :))
and especially because it offers so much possibilities, see graph here
https://pandoc.org/
You never know what you will need one day...

Jacques

Re: [Discussion] documentation framework for OFBiz

[Jacques Le Roux <ja...@les7arts.com>]

Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :
> On 17 October 2017 at 20:25, Michael Brohl <mi...@ecomify.de> wrote:
>
>
>> I assume that we can use any Asciidoc editor and need not to use
>> Asciidoctor?
>>
> Hi Michael,
>
> Asciidoctor is not an editor, it's a text processor that can convert
> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
> (https://pandoc.org/).
>
> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
> for IntelliJ IDEA. Your tastes may vary.
>
> Cheers
>
> Paul Foxworthy
>
Hi Paul,

Do you know if there are there good reasons to favor Asciidoctor over Pandoc?
I'm more in favour of the later because now I know it (thanks to you :)) and especially because it offers so much possibilities, see graph here 
https://pandoc.org/
You never know what you will need one day...

Jacques

Re: [Discussion] documentation framework for OFBiz

[Paul Foxworthy <pa...@cohsoft.com.au>]

On 17 October 2017 at 20:25, Michael Brohl <mi...@ecomify.de> wrote:


> I assume that we can use any Asciidoc editor and need not to use
> Asciidoctor?
>

Hi Michael,

Asciidoctor is not an editor, it's a text processor that can convert
AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
(https://pandoc.org/).

One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
for IntelliJ IDEA. Your tastes may vary.

Cheers

Paul Foxworthy

-- 
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Australia

Phone: +61 3 9585 6788
Web: http://www.coherentsoftware.com.au/
Email: info@coherentsoftware.com.au

Re: [Discussion] documentation framework for OFBiz

[Michael Brohl <mi...@ecomify.de>]

Big +1 for this initiative!

I have not much to add to Taher's proposal and Sharan's viewpoint.

I assume that we can use any Asciidoc editor and need not to use 
Asciidoctor?

I think we have to decide what we will do with our Wiki based 
documentation then. If we have up-to-date documentation in the 
components and can generate up-to-date documentation every night, pretty 
much of the Wiki documentation would be obsolete. A simple link to the 
generated documentation would be enough, right?

For new code in framework and plugins, I would strongly recommend to 
have mandatory documentation as part of the first commit to the codebase 
to assure a good initial start.

I think we should just start with a proof-of-concept by moving some 
small part of the documentation to Asciidoc and into the codebase.

Would be a great starting point for new contributors also.

Best regards,

Michael


Am 17.10.17 um 10:30 schrieb Sharan Foga:
> Hi Taher
>
> It's great that this conversation has started again. It would be great 
> to actually start to do something about the integrated help system 
> within OFBiz itself. We have found limitations with the docbook 
> implementation we have, so now have a better idea of what we want to 
> achieve.
>
> In the past we've talked a lot about DITA but to me it seemed a lot 
> more complex to understand, structure and generally get started. I've 
> briefly played about with Ascidoc and it seems pretty simple enough to 
> get the hang of and that to me is an important thing. I also like the 
> idea of being able to render multiple formats (and it would be good to 
> make them look nicer and easier to read).
>
> Getting a good and functioning help framework into our codebase is 
> long overdue and I'm sure will add some great benefits and also 
> encourage documentation contributions from our community.
>
> Big +1 from me!
>
> Thanks
> Sharan
>
>
> On 17/10/17 10:01, Taher Alkhateeb wrote:
>> Hello Folks,
>>
>> We've had this discussion multiple times in the past, but I think I
>> have a more concrete idea this time for solving this problem. In the
>> past few weeks we've been working internally in Pythys to figure out
>> the best way to write and distribute documentation, and I think most
>> of that is applicable to OFBiz.
>>
>> In a nutshell, here is the idea (practically) for how to proceed:
>>
>> - The documentation language to use is Asciidoc
>> - The documentation tool is Asciidoctor
>> - Publishing happens through Gradle using the asciidoctor gradle
>> plugin (not the OFBiz framework or anything else).
>> - The only place where we write documentation is inside the code base
>> - Every component contains its own documentation
>> - General documentation goes to either a standalone directory or a
>> generic component like common or base
>> - As much as possible, documentation files are small and focused on
>> one topic. And then other longer documents are constructed from these
>> snippets of documentation.
>> - We publish to all formats including PDF for users, or HTML for
>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>> help system, instead it just renders generated HTML.
>>
>> As I've worked extensively with Asciidoc I find it easy to pickup
>> (like markdown) but also modular (like docbook and dita). It's also
>> neat that you can sprinkle variables all around in your document so
>> that update is no longer a painful grepping process.
>>
>> Would love to hear your thoughts on this.
>>
>> Cheers,
>>
>> Taher Alkhateeb
>
>

Re: [Discussion] documentation framework for OFBiz

[Sharan Foga <sh...@gmail.com>]

Hi Taher

It's great that this conversation has started again. It would be great 
to actually start to do something about the integrated help system 
within OFBiz itself. We have found limitations with the docbook 
implementation we have, so now have a better idea of what we want to 
achieve.

In the past we've talked a lot about DITA but to me it seemed a lot more 
complex to understand, structure and generally get started. I've briefly 
played about with Ascidoc and it seems pretty simple enough to get the 
hang of and that to me is an important thing. I also like the idea of 
being able to render multiple formats (and it would be good to make them 
look nicer and easier to read).

Getting a good and functioning help framework into our codebase is long 
overdue and I'm sure will add some great benefits and also encourage 
documentation contributions from our community.

Big +1 from me!

Thanks
Sharan


On 17/10/17 10:01, Taher Alkhateeb wrote:
> Hello Folks,
>
> We've had this discussion multiple times in the past, but I think I
> have a more concrete idea this time for solving this problem. In the
> past few weeks we've been working internally in Pythys to figure out
> the best way to write and distribute documentation, and I think most
> of that is applicable to OFBiz.
>
> In a nutshell, here is the idea (practically) for how to proceed:
>
> - The documentation language to use is Asciidoc
> - The documentation tool is Asciidoctor
> - Publishing happens through Gradle using the asciidoctor gradle
> plugin (not the OFBiz framework or anything else).
> - The only place where we write documentation is inside the code base
> - Every component contains its own documentation
> - General documentation goes to either a standalone directory or a
> generic component like common or base
> - As much as possible, documentation files are small and focused on
> one topic. And then other longer documents are constructed from these
> snippets of documentation.
> - We publish to all formats including PDF for users, or HTML for
> embedded help and wiki pages. So OFBiz does not parse docbook for its
> help system, instead it just renders generated HTML.
>
> As I've worked extensively with Asciidoc I find it easy to pickup
> (like markdown) but also modular (like docbook and dita). It's also
> neat that you can sprinkle variables all around in your document so
> that update is no longer a painful grepping process.
>
> Would love to hear your thoughts on this.
>
> Cheers,
>
> Taher Alkhateeb

Re: [Discussion] documentation framework for OFBiz

[gil portenseigne <gi...@nereide.fr>]

:D indeed !

I will try it out tonight !

Gil


On 15/01/2018 09:27, Taher Alkhateeb wrote:
> Hi Gil,
>
> There is nothing simpler than linking docs together. Code snippet:
>
> include::relative/path/to/document/document-name.adoc[]
>
> Wow right :)
>
> On Mon, Jan 15, 2018 at 11:15 AM, gil portenseigne
> <gi...@nereide.fr> wrote:
>> Hello Taher,
>>
>> I did try your patch and played a bit with the asciidoctor integration you
>> provide, this week-end.
>>
>> That's quite simple, i like it, i will play a bit more with it to find the
>> good way to links docs files between them.
>>
>> Thanks !
>>
>> Gil
>>
>>
>>
>> On 12/01/2018 17:36, Taher Alkhateeb wrote:
>>> Hello everyone,
>>>
>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>> have a small patch in [1] that provides the PoC for integrating
>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>> instructions on how to run it. Essentially, this allows you to create
>>> documentation for any component by simply creating a src/docs/asciidoc
>>> directory and putting files inside.
>>>
>>> This solution is flexible and allows us to build bigger designs on top
>>> of it. Please review it and tell me if you like the general design.
>>>
>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>
>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>> <sl...@gmail.com> wrote:
>>>> Hello Folks,
>>>>
>>>> We've had this discussion multiple times in the past, but I think I
>>>> have a more concrete idea this time for solving this problem. In the
>>>> past few weeks we've been working internally in Pythys to figure out
>>>> the best way to write and distribute documentation, and I think most
>>>> of that is applicable to OFBiz.
>>>>
>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>
>>>> - The documentation language to use is Asciidoc
>>>> - The documentation tool is Asciidoctor
>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>> plugin (not the OFBiz framework or anything else).
>>>> - The only place where we write documentation is inside the code base
>>>> - Every component contains its own documentation
>>>> - General documentation goes to either a standalone directory or a
>>>> generic component like common or base
>>>> - As much as possible, documentation files are small and focused on
>>>> one topic. And then other longer documents are constructed from these
>>>> snippets of documentation.
>>>> - We publish to all formats including PDF for users, or HTML for
>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>> help system, instead it just renders generated HTML.
>>>>
>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>> neat that you can sprinkle variables all around in your document so
>>>> that update is no longer a painful grepping process.
>>>>
>>>> Would love to hear your thoughts on this.
>>>>
>>>> Cheers,
>>>>
>>>> Taher Alkhateeb
>>

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

Hi Gil,

There is nothing simpler than linking docs together. Code snippet:

include::relative/path/to/document/document-name.adoc[]

Wow right :)

On Mon, Jan 15, 2018 at 11:15 AM, gil portenseigne
<gi...@nereide.fr> wrote:
> Hello Taher,
>
> I did try your patch and played a bit with the asciidoctor integration you
> provide, this week-end.
>
> That's quite simple, i like it, i will play a bit more with it to find the
> good way to links docs files between them.
>
> Thanks !
>
> Gil
>
>
>
> On 12/01/2018 17:36, Taher Alkhateeb wrote:
>>
>> Hello everyone,
>>
>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>> have a small patch in [1] that provides the PoC for integrating
>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>> instructions on how to run it. Essentially, this allows you to create
>> documentation for any component by simply creating a src/docs/asciidoc
>> directory and putting files inside.
>>
>> This solution is flexible and allows us to build bigger designs on top
>> of it. Please review it and tell me if you like the general design.
>>
>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>
>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>> <sl...@gmail.com> wrote:
>>>
>>> Hello Folks,
>>>
>>> We've had this discussion multiple times in the past, but I think I
>>> have a more concrete idea this time for solving this problem. In the
>>> past few weeks we've been working internally in Pythys to figure out
>>> the best way to write and distribute documentation, and I think most
>>> of that is applicable to OFBiz.
>>>
>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>
>>> - The documentation language to use is Asciidoc
>>> - The documentation tool is Asciidoctor
>>> - Publishing happens through Gradle using the asciidoctor gradle
>>> plugin (not the OFBiz framework or anything else).
>>> - The only place where we write documentation is inside the code base
>>> - Every component contains its own documentation
>>> - General documentation goes to either a standalone directory or a
>>> generic component like common or base
>>> - As much as possible, documentation files are small and focused on
>>> one topic. And then other longer documents are constructed from these
>>> snippets of documentation.
>>> - We publish to all formats including PDF for users, or HTML for
>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>> help system, instead it just renders generated HTML.
>>>
>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>> (like markdown) but also modular (like docbook and dita). It's also
>>> neat that you can sprinkle variables all around in your document so
>>> that update is no longer a painful grepping process.
>>>
>>> Would love to hear your thoughts on this.
>>>
>>> Cheers,
>>>
>>> Taher Alkhateeb
>
>

Re: [Discussion] documentation framework for OFBiz

[gil portenseigne <gi...@nereide.fr>]

Hello Taher,

I did try your patch and played a bit with the asciidoctor integration 
you provide, this week-end.

That's quite simple, i like it, i will play a bit more with it to find 
the good way to links docs files between them.

Thanks !

Gil


On 12/01/2018 17:36, Taher Alkhateeb wrote:
> Hello everyone,
>
> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
> have a small patch in [1] that provides the PoC for integrating
> asciidoctor with OFBiz. I also provided in the the JIRA [1]
> instructions on how to run it. Essentially, this allows you to create
> documentation for any component by simply creating a src/docs/asciidoc
> directory and putting files inside.
>
> This solution is flexible and allows us to build bigger designs on top
> of it. Please review it and tell me if you like the general design.
>
> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>
> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
> <sl...@gmail.com> wrote:
>> Hello Folks,
>>
>> We've had this discussion multiple times in the past, but I think I
>> have a more concrete idea this time for solving this problem. In the
>> past few weeks we've been working internally in Pythys to figure out
>> the best way to write and distribute documentation, and I think most
>> of that is applicable to OFBiz.
>>
>> In a nutshell, here is the idea (practically) for how to proceed:
>>
>> - The documentation language to use is Asciidoc
>> - The documentation tool is Asciidoctor
>> - Publishing happens through Gradle using the asciidoctor gradle
>> plugin (not the OFBiz framework or anything else).
>> - The only place where we write documentation is inside the code base
>> - Every component contains its own documentation
>> - General documentation goes to either a standalone directory or a
>> generic component like common or base
>> - As much as possible, documentation files are small and focused on
>> one topic. And then other longer documents are constructed from these
>> snippets of documentation.
>> - We publish to all formats including PDF for users, or HTML for
>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>> help system, instead it just renders generated HTML.
>>
>> As I've worked extensively with Asciidoc I find it easy to pickup
>> (like markdown) but also modular (like docbook and dita). It's also
>> neat that you can sprinkle variables all around in your document so
>> that update is no longer a painful grepping process.
>>
>> Would love to hear your thoughts on this.
>>
>> Cheers,
>>
>> Taher Alkhateeb

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

Also thinking about it just after clicking send, maybe there is no
need for the publishComponentDocs and publishAllComponentsDocs tasks
because we should treat all OFBiz documentation as one piece. and
Instead we can have a ./gradlew publishPluginDocs. So throwing another
idea in the pile

On Wed, Jan 17, 2018 at 6:54 PM, Taher Alkhateeb
<sl...@gmail.com> wrote:
> So I have thought of a few ways to implement our documentation
> structure and I would like to share my ideas with everyone to see what
> you prefer to go with. Here goes:
>
> - First, let's categorize documentation as:
>   - component-specific
>   - general documentation
> - component specific documentation lives inside the component in
> "/src/docs/asciidoc". It is a self contained piece of documentation.
> - Every component has only _one_ publishable document. There is a
> methodology in asciidoctor to denote public and private documents.
> private documents will not be published but only included in other
> documents. This way we can make a modular documentation for each
> component while publishing only one output.
> - general documentation (i'm still scratching my head over this one)
> could be placed maybe in framework/base. What it does is explain high
> level information about the framework and explain general conceptual
> principles of how things work.
> - We can combine the entire documentation of everything (framework +
> applications) in a single document that references all the other
> documents and maybe we can place it at the top-level directory and
> call it something like ofbiz-documentation.adoc
> - Plugins are not included in the full documentation, they are self
> contained and are not part of the _big_ published manual. instead each
> plugin has its own mini manual.
> - We declare three gradle tasks similar to the below:
>   - "./gradlew publishComponentDocs": publish documentation for a
> specific component / plugin which requires a componentName flag.
>   - "./gradlew publishAllComponentsDocs": publish documentation for
> all components / plugins
>   - "./gradlew publishOfbizDocs": publish the master documentation
> manual that combines everything.
>
> This is a brain dump so I leave it to you fine folks to refine the
> ideas and decide where we should go.
>
> Cheers,
>
> Taher Alkhateeb
>
> On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <cr...@fossfolks.com> wrote:
>> I think the doc structure ought to mirror the menu in the software, or are
>> you talking about how a doc itself is laid out?
>>
>>
>>
>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>>
>>> Hi Taher
>>>
>>> Great work! I tried it out and found it simple and easy to use (and
>>> write!). When can we start writing ? :-)
>>>
>>> I was thinking to start with basic descriptions of each of the
>>> applications, then see how it evolves from there. We can maybe recover some
>>> documentation content from various sources including our existing online
>>> help system and the wiki.
>>>
>>> The documentation structure will maybe need some thought, and we may need
>>> to sort out some common template or guidelines around it.
>>>
>>> Thanks
>>> Sharan
>>>
>>> On 2018-01-14 12:33, "Sharan Foga"<sh...@apache.org> wrote:
>>>>
>>>> Excellent news Taher!
>>>>
>>>> Thanks very much for your effort on this. I'll aim to try it out this
>>>> week and come back with any feedback.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com> wrote:
>>>>>
>>>>> Hello everyone,
>>>>>
>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>> directory and putting files inside.
>>>>>
>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>> of it. Please review it and tell me if you like the general design.
>>>>>
>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>
>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>> <sl...@gmail.com> wrote:
>>>>>>
>>>>>> Hello Folks,
>>>>>>
>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>> the best way to write and distribute documentation, and I think most
>>>>>> of that is applicable to OFBiz.
>>>>>>
>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>
>>>>>> - The documentation language to use is Asciidoc
>>>>>> - The documentation tool is Asciidoctor
>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>> - The only place where we write documentation is inside the code base
>>>>>> - Every component contains its own documentation
>>>>>> - General documentation goes to either a standalone directory or a
>>>>>> generic component like common or base
>>>>>> - As much as possible, documentation files are small and focused on
>>>>>> one topic. And then other longer documents are constructed from these
>>>>>> snippets of documentation.
>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>> help system, instead it just renders generated HTML.
>>>>>>
>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>> that update is no longer a painful grepping process.
>>>>>>
>>>>>> Would love to hear your thoughts on this.
>>>>>>
>>>>>> Cheers,
>>>>>>
>>>>>> Taher Alkhateeb
>>
>>

Re: [Discussion] documentation framework for OFBiz

[Jacques Le Roux <ja...@les7arts.com>]

Inline...


Le 18/01/2018 à 13:54, Sharan Foga a écrit :
> Hi Taher
>
> I've included some comments inline.
>
> On 2018-01-17 16:54, Taher Alkhateeb <sl...@gmail.com> wrote:
>> So I have thought of a few ways to implement our documentation
>> structure and I would like to share my ideas with everyone to see what
>> you prefer to go with. Here goes:
>>
>> - First, let's categorize documentation as:
>>    - component-specific
>>    - general documentation
> I like this as it is a simple and easy way for us to do our first split. In the past we have tried to put everything together in a way that doesn't really fit, so doing an initial is it this or that, makes it a lot easier.
+1

>> - component specific documentation lives inside the component in
>> "/src/docs/asciidoc". It is a self contained piece of documentation.
>> - Every component has only _one_ publishable document. There is a
>> methodology in asciidoctor to denote public and private documents.
>> private documents will not be published but only included in other
>> documents. This way we can make a modular documentation for each
>> component while publishing only one output.
> I like the idea of only one publishable document per component. That means that we have a fixed scope for what the documentation needs to cover (so no documentation creep). I'm sure we will get interlinking between components so can plan for it and link when ready.
+1 and +1 for inter-links idea

>> - general documentation (i'm still scratching my head over this one)
>> could be placed maybe in framework/base. What it does is explain high
>> level information about the framework and explain general conceptual
>> principles of how things work.
I'm not sure this can be called general documentation. I was thinking at another place initially, one place where people should look intuitively, like 
a documentation sub-dir of root. But we need to define what we call general documentation.

>> - We can combine the entire documentation of everything (framework +
>> applications) in a single document that references all the other
>> documents and maybe we can place it at the top-level directory and
>> call it something like ofbiz-documentation.adoc
> As long as people can easily navigate it and find what they want quickly then one document could be the solution. At least we can start with that and if does start to become too heavy then look at re-arranging it or splitting it up.
That sounds like a good idea, finding an ofbiz-documentation.adoc file is as easy as finding a documentation sub-dir of root. But then we need to 
remember that it's not often the content that confuse people but how to access it. So we need to think about the structure of this document (like 
separating end users and technical doc at the 1st level. Maybe we can think about having end users and technical doc separated in component?

> In the past I think all the details from the online help were published as a consolidated html file via the OFBiz cms. I think it was too linked to the individual screens so as standalone document without the screens, it wasn't as useful as it could be.
I think people were also not much aware of this document, so it got not much critics and was not improved

> - Plugins are not included in the full documentation, they are self
> contained and are not part of the _big_ published manual. instead each
> plugin has its own mini manual.
> +1 on this. We will have to maintain the official plugin documentation, and I would see that people writing their own plugins can use this same mechanism to include their specific documentation.
Sure +1!

>
>
>> - We declare three gradle tasks similar to the below:
>>    - "./gradlew publishComponentDocs": publish documentation for a
>> specific component / plugin which requires a componentName flag.
>>    - "./gradlew publishAllComponentsDocs": publish documentation for
>> all components / plugins
>>    - "./gradlew publishOfbizDocs": publish the master documentation
>> manual that combines everything.
>>
> As per your later response, I think we could reduce the gradle tasks to one for the framework+core application docs and one for the plugins.
>
> Thanks for sharing - you have some good ideas here.  Let's keep the discussion going :-) so anyone with other ideas, comments and feedback, please feel free to join the conversation.
I agree, let's continue to share :)

Jacques
>
> Thanks
> Sharan
>
>
>> This is a brain dump so I leave it to you fine folks to refine the
>> ideas and decide where we should go.
>>
>> Cheers,
>>
>> Taher Alkhateeb
>>
>> On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <cr...@fossfolks.com> wrote:
>>> I think the doc structure ought to mirror the menu in the software, or are
>>> you talking about how a doc itself is laid out?
>>>
>>>
>>>
>>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>>> Hi Taher
>>>>
>>>> Great work! I tried it out and found it simple and easy to use (and
>>>> write!). When can we start writing ? :-)
>>>>
>>>> I was thinking to start with basic descriptions of each of the
>>>> applications, then see how it evolves from there. We can maybe recover some
>>>> documentation content from various sources including our existing online
>>>> help system and the wiki.
>>>>
>>>> The documentation structure will maybe need some thought, and we may need
>>>> to sort out some common template or guidelines around it.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-14 12:33, "Sharan Foga"<sh...@apache.org> wrote:
>>>>> Excellent news Taher!
>>>>>
>>>>> Thanks very much for your effort on this. I'll aim to try it out this
>>>>> week and come back with any feedback.
>>>>>
>>>>> Thanks
>>>>> Sharan
>>>>>
>>>>> On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com> wrote:
>>>>>> Hello everyone,
>>>>>>
>>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>>> directory and putting files inside.
>>>>>>
>>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>>> of it. Please review it and tell me if you like the general design.
>>>>>>
>>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>>
>>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>>> <sl...@gmail.com> wrote:
>>>>>>> Hello Folks,
>>>>>>>
>>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>>> the best way to write and distribute documentation, and I think most
>>>>>>> of that is applicable to OFBiz.
>>>>>>>
>>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>>
>>>>>>> - The documentation language to use is Asciidoc
>>>>>>> - The documentation tool is Asciidoctor
>>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>>> - The only place where we write documentation is inside the code base
>>>>>>> - Every component contains its own documentation
>>>>>>> - General documentation goes to either a standalone directory or a
>>>>>>> generic component like common or base
>>>>>>> - As much as possible, documentation files are small and focused on
>>>>>>> one topic. And then other longer documents are constructed from these
>>>>>>> snippets of documentation.
>>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>>> help system, instead it just renders generated HTML.
>>>>>>>
>>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>>> that update is no longer a painful grepping process.
>>>>>>>
>>>>>>> Would love to hear your thoughts on this.
>>>>>>>
>>>>>>> Cheers,
>>>>>>>
>>>>>>> Taher Alkhateeb
>>>

Re: [Discussion] documentation framework for OFBiz

[Sharan Foga <sh...@apache.org>]

Hi Taher

I've included some comments inline.

On 2018-01-17 16:54, Taher Alkhateeb <sl...@gmail.com> wrote: 
> So I have thought of a few ways to implement our documentation
> structure and I would like to share my ideas with everyone to see what
> you prefer to go with. Here goes:
> 
> - First, let's categorize documentation as:
>   - component-specific
>   - general documentation

I like this as it is a simple and easy way for us to do our first split. In the past we have tried to put everything together in a way that doesn't really fit, so doing an initial is it this or that, makes it a lot easier.

> - component specific documentation lives inside the component in
> "/src/docs/asciidoc". It is a self contained piece of documentation.
> - Every component has only _one_ publishable document. There is a
> methodology in asciidoctor to denote public and private documents.
> private documents will not be published but only included in other
> documents. This way we can make a modular documentation for each
> component while publishing only one output.

I like the idea of only one publishable document per component. That means that we have a fixed scope for what the documentation needs to cover (so no documentation creep). I'm sure we will get interlinking between components so can plan for it and link when ready.


> - general documentation (i'm still scratching my head over this one)
> could be placed maybe in framework/base. What it does is explain high
> level information about the framework and explain general conceptual
> principles of how things work.
> - We can combine the entire documentation of everything (framework +
> applications) in a single document that references all the other
> documents and maybe we can place it at the top-level directory and
> call it something like ofbiz-documentation.adoc

As long as people can easily navigate it and find what they want quickly then one document could be the solution. At least we can start with that and if does start to become too heavy then look at re-arranging it or splitting it up.

In the past I think all the details from the online help were published as a consolidated html file via the OFBiz cms. I think it was too linked to the individual screens so as standalone document without the screens, it wasn't as useful as it could be.


> - Plugins are not included in the full documentation, they are self
> contained and are not part of the _big_ published manual. instead each
> plugin has its own mini manual.

+1 on this. We will have to maintain the official plugin documentation, and I would see that people writing their own plugins can use this same mechanism to include their specific documentation.


> - We declare three gradle tasks similar to the below:
>   - "./gradlew publishComponentDocs": publish documentation for a
> specific component / plugin which requires a componentName flag.
>   - "./gradlew publishAllComponentsDocs": publish documentation for
> all components / plugins
>   - "./gradlew publishOfbizDocs": publish the master documentation
> manual that combines everything.
> 

As per your later response, I think we could reduce the gradle tasks to one for the framework+core application docs and one for the plugins.

Thanks for sharing - you have some good ideas here.  Let's keep the discussion going :-) so anyone with other ideas, comments and feedback, please feel free to join the conversation.

Thanks
Sharan


> This is a brain dump so I leave it to you fine folks to refine the
> ideas and decide where we should go.
> 
> Cheers,
> 
> Taher Alkhateeb
> 
> On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <cr...@fossfolks.com> wrote:
> > I think the doc structure ought to mirror the menu in the software, or are
> > you talking about how a doc itself is laid out?
> >
> >
> >
> > On 01/17/2018 09:25 AM, Sharan Foga wrote:
> >>
> >> Hi Taher
> >>
> >> Great work! I tried it out and found it simple and easy to use (and
> >> write!). When can we start writing ? :-)
> >>
> >> I was thinking to start with basic descriptions of each of the
> >> applications, then see how it evolves from there. We can maybe recover some
> >> documentation content from various sources including our existing online
> >> help system and the wiki.
> >>
> >> The documentation structure will maybe need some thought, and we may need
> >> to sort out some common template or guidelines around it.
> >>
> >> Thanks
> >> Sharan
> >>
> >> On 2018-01-14 12:33, "Sharan Foga"<sh...@apache.org> wrote:
> >>>
> >>> Excellent news Taher!
> >>>
> >>> Thanks very much for your effort on this. I'll aim to try it out this
> >>> week and come back with any feedback.
> >>>
> >>> Thanks
> >>> Sharan
> >>>
> >>> On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com> wrote:
> >>>>
> >>>> Hello everyone,
> >>>>
> >>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
> >>>> have a small patch in [1] that provides the PoC for integrating
> >>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
> >>>> instructions on how to run it. Essentially, this allows you to create
> >>>> documentation for any component by simply creating a src/docs/asciidoc
> >>>> directory and putting files inside.
> >>>>
> >>>> This solution is flexible and allows us to build bigger designs on top
> >>>> of it. Please review it and tell me if you like the general design.
> >>>>
> >>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
> >>>>
> >>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
> >>>> <sl...@gmail.com> wrote:
> >>>>>
> >>>>> Hello Folks,
> >>>>>
> >>>>> We've had this discussion multiple times in the past, but I think I
> >>>>> have a more concrete idea this time for solving this problem. In the
> >>>>> past few weeks we've been working internally in Pythys to figure out
> >>>>> the best way to write and distribute documentation, and I think most
> >>>>> of that is applicable to OFBiz.
> >>>>>
> >>>>> In a nutshell, here is the idea (practically) for how to proceed:
> >>>>>
> >>>>> - The documentation language to use is Asciidoc
> >>>>> - The documentation tool is Asciidoctor
> >>>>> - Publishing happens through Gradle using the asciidoctor gradle
> >>>>> plugin (not the OFBiz framework or anything else).
> >>>>> - The only place where we write documentation is inside the code base
> >>>>> - Every component contains its own documentation
> >>>>> - General documentation goes to either a standalone directory or a
> >>>>> generic component like common or base
> >>>>> - As much as possible, documentation files are small and focused on
> >>>>> one topic. And then other longer documents are constructed from these
> >>>>> snippets of documentation.
> >>>>> - We publish to all formats including PDF for users, or HTML for
> >>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
> >>>>> help system, instead it just renders generated HTML.
> >>>>>
> >>>>> As I've worked extensively with Asciidoc I find it easy to pickup
> >>>>> (like markdown) but also modular (like docbook and dita). It's also
> >>>>> neat that you can sprinkle variables all around in your document so
> >>>>> that update is no longer a painful grepping process.
> >>>>>
> >>>>> Would love to hear your thoughts on this.
> >>>>>
> >>>>> Cheers,
> >>>>>
> >>>>> Taher Alkhateeb
> >
> >
> 

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

I'm not sure, but I think we should document "everything" like user,
developer, etc. It's up to all of us to decide and I have no strong
opinion on this.

On Wed, Jan 17, 2018 at 6:56 PM, Craig Parker <cr...@fossfolks.com> wrote:
> And I'm just realizing... You're not talking end user docs are you?
>
>
>
> On 01/17/2018 10:54 AM, Taher Alkhateeb wrote:
>>
>> So I have thought of a few ways to implement our documentation
>> structure and I would like to share my ideas with everyone to see what
>> you prefer to go with. Here goes:
>>
>> - First, let's categorize documentation as:
>>    - component-specific
>>    - general documentation
>> - component specific documentation lives inside the component in
>> "/src/docs/asciidoc". It is a self contained piece of documentation.
>> - Every component has only _one_ publishable document. There is a
>> methodology in asciidoctor to denote public and private documents.
>> private documents will not be published but only included in other
>> documents. This way we can make a modular documentation for each
>> component while publishing only one output.
>> - general documentation (i'm still scratching my head over this one)
>> could be placed maybe in framework/base. What it does is explain high
>> level information about the framework and explain general conceptual
>> principles of how things work.
>> - We can combine the entire documentation of everything (framework +
>> applications) in a single document that references all the other
>> documents and maybe we can place it at the top-level directory and
>> call it something like ofbiz-documentation.adoc
>> - Plugins are not included in the full documentation, they are self
>> contained and are not part of the _big_ published manual. instead each
>> plugin has its own mini manual.
>> - We declare three gradle tasks similar to the below:
>>    - "./gradlew publishComponentDocs": publish documentation for a
>> specific component / plugin which requires a componentName flag.
>>    - "./gradlew publishAllComponentsDocs": publish documentation for
>> all components / plugins
>>    - "./gradlew publishOfbizDocs": publish the master documentation
>> manual that combines everything.
>>
>> This is a brain dump so I leave it to you fine folks to refine the
>> ideas and decide where we should go.
>>
>> Cheers,
>>
>> Taher Alkhateeb
>>
>> On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <cr...@fossfolks.com> wrote:
>>>
>>> I think the doc structure ought to mirror the menu in the software, or
>>> are
>>> you talking about how a doc itself is laid out?
>>>
>>>
>>>
>>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>>>
>>>> Hi Taher
>>>>
>>>> Great work! I tried it out and found it simple and easy to use (and
>>>> write!). When can we start writing ? :-)
>>>>
>>>> I was thinking to start with basic descriptions of each of the
>>>> applications, then see how it evolves from there. We can maybe recover
>>>> some
>>>> documentation content from various sources including our existing online
>>>> help system and the wiki.
>>>>
>>>> The documentation structure will maybe need some thought, and we may
>>>> need
>>>> to sort out some common template or guidelines around it.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-14 12:33, "Sharan Foga"<sh...@apache.org> wrote:
>>>>>
>>>>> Excellent news Taher!
>>>>>
>>>>> Thanks very much for your effort on this. I'll aim to try it out this
>>>>> week and come back with any feedback.
>>>>>
>>>>> Thanks
>>>>> Sharan
>>>>>
>>>>> On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com>
>>>>> wrote:
>>>>>>
>>>>>> Hello everyone,
>>>>>>
>>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>>> directory and putting files inside.
>>>>>>
>>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>>> of it. Please review it and tell me if you like the general design.
>>>>>>
>>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>>
>>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>>> <sl...@gmail.com> wrote:
>>>>>>>
>>>>>>> Hello Folks,
>>>>>>>
>>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>>> the best way to write and distribute documentation, and I think most
>>>>>>> of that is applicable to OFBiz.
>>>>>>>
>>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>>
>>>>>>> - The documentation language to use is Asciidoc
>>>>>>> - The documentation tool is Asciidoctor
>>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>>> - The only place where we write documentation is inside the code base
>>>>>>> - Every component contains its own documentation
>>>>>>> - General documentation goes to either a standalone directory or a
>>>>>>> generic component like common or base
>>>>>>> - As much as possible, documentation files are small and focused on
>>>>>>> one topic. And then other longer documents are constructed from these
>>>>>>> snippets of documentation.
>>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>>> help system, instead it just renders generated HTML.
>>>>>>>
>>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>>> that update is no longer a painful grepping process.
>>>>>>>
>>>>>>> Would love to hear your thoughts on this.
>>>>>>>
>>>>>>> Cheers,
>>>>>>>
>>>>>>> Taher Alkhateeb
>>>
>>>
>

Re: [Discussion] documentation framework for OFBiz

[Craig Parker <cr...@fossfolks.com>]

And I'm just realizing... You're not talking end user docs are you?


On 01/17/2018 10:54 AM, Taher Alkhateeb wrote:
> So I have thought of a few ways to implement our documentation
> structure and I would like to share my ideas with everyone to see what
> you prefer to go with. Here goes:
>
> - First, let's categorize documentation as:
>    - component-specific
>    - general documentation
> - component specific documentation lives inside the component in
> "/src/docs/asciidoc". It is a self contained piece of documentation.
> - Every component has only _one_ publishable document. There is a
> methodology in asciidoctor to denote public and private documents.
> private documents will not be published but only included in other
> documents. This way we can make a modular documentation for each
> component while publishing only one output.
> - general documentation (i'm still scratching my head over this one)
> could be placed maybe in framework/base. What it does is explain high
> level information about the framework and explain general conceptual
> principles of how things work.
> - We can combine the entire documentation of everything (framework +
> applications) in a single document that references all the other
> documents and maybe we can place it at the top-level directory and
> call it something like ofbiz-documentation.adoc
> - Plugins are not included in the full documentation, they are self
> contained and are not part of the _big_ published manual. instead each
> plugin has its own mini manual.
> - We declare three gradle tasks similar to the below:
>    - "./gradlew publishComponentDocs": publish documentation for a
> specific component / plugin which requires a componentName flag.
>    - "./gradlew publishAllComponentsDocs": publish documentation for
> all components / plugins
>    - "./gradlew publishOfbizDocs": publish the master documentation
> manual that combines everything.
>
> This is a brain dump so I leave it to you fine folks to refine the
> ideas and decide where we should go.
>
> Cheers,
>
> Taher Alkhateeb
>
> On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <cr...@fossfolks.com> wrote:
>> I think the doc structure ought to mirror the menu in the software, or are
>> you talking about how a doc itself is laid out?
>>
>>
>>
>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>> Hi Taher
>>>
>>> Great work! I tried it out and found it simple and easy to use (and
>>> write!). When can we start writing ? :-)
>>>
>>> I was thinking to start with basic descriptions of each of the
>>> applications, then see how it evolves from there. We can maybe recover some
>>> documentation content from various sources including our existing online
>>> help system and the wiki.
>>>
>>> The documentation structure will maybe need some thought, and we may need
>>> to sort out some common template or guidelines around it.
>>>
>>> Thanks
>>> Sharan
>>>
>>> On 2018-01-14 12:33, "Sharan Foga"<sh...@apache.org> wrote:
>>>> Excellent news Taher!
>>>>
>>>> Thanks very much for your effort on this. I'll aim to try it out this
>>>> week and come back with any feedback.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com> wrote:
>>>>> Hello everyone,
>>>>>
>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>> directory and putting files inside.
>>>>>
>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>> of it. Please review it and tell me if you like the general design.
>>>>>
>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>
>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>> <sl...@gmail.com> wrote:
>>>>>> Hello Folks,
>>>>>>
>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>> the best way to write and distribute documentation, and I think most
>>>>>> of that is applicable to OFBiz.
>>>>>>
>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>
>>>>>> - The documentation language to use is Asciidoc
>>>>>> - The documentation tool is Asciidoctor
>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>> - The only place where we write documentation is inside the code base
>>>>>> - Every component contains its own documentation
>>>>>> - General documentation goes to either a standalone directory or a
>>>>>> generic component like common or base
>>>>>> - As much as possible, documentation files are small and focused on
>>>>>> one topic. And then other longer documents are constructed from these
>>>>>> snippets of documentation.
>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>> help system, instead it just renders generated HTML.
>>>>>>
>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>> that update is no longer a painful grepping process.
>>>>>>
>>>>>> Would love to hear your thoughts on this.
>>>>>>
>>>>>> Cheers,
>>>>>>
>>>>>> Taher Alkhateeb
>>

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

So I have thought of a few ways to implement our documentation
structure and I would like to share my ideas with everyone to see what
you prefer to go with. Here goes:

- First, let's categorize documentation as:
  - component-specific
  - general documentation
- component specific documentation lives inside the component in
"/src/docs/asciidoc". It is a self contained piece of documentation.
- Every component has only _one_ publishable document. There is a
methodology in asciidoctor to denote public and private documents.
private documents will not be published but only included in other
documents. This way we can make a modular documentation for each
component while publishing only one output.
- general documentation (i'm still scratching my head over this one)
could be placed maybe in framework/base. What it does is explain high
level information about the framework and explain general conceptual
principles of how things work.
- We can combine the entire documentation of everything (framework +
applications) in a single document that references all the other
documents and maybe we can place it at the top-level directory and
call it something like ofbiz-documentation.adoc
- Plugins are not included in the full documentation, they are self
contained and are not part of the _big_ published manual. instead each
plugin has its own mini manual.
- We declare three gradle tasks similar to the below:
  - "./gradlew publishComponentDocs": publish documentation for a
specific component / plugin which requires a componentName flag.
  - "./gradlew publishAllComponentsDocs": publish documentation for
all components / plugins
  - "./gradlew publishOfbizDocs": publish the master documentation
manual that combines everything.

This is a brain dump so I leave it to you fine folks to refine the
ideas and decide where we should go.

Cheers,

Taher Alkhateeb

On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <cr...@fossfolks.com> wrote:
> I think the doc structure ought to mirror the menu in the software, or are
> you talking about how a doc itself is laid out?
>
>
>
> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>
>> Hi Taher
>>
>> Great work! I tried it out and found it simple and easy to use (and
>> write!). When can we start writing ? :-)
>>
>> I was thinking to start with basic descriptions of each of the
>> applications, then see how it evolves from there. We can maybe recover some
>> documentation content from various sources including our existing online
>> help system and the wiki.
>>
>> The documentation structure will maybe need some thought, and we may need
>> to sort out some common template or guidelines around it.
>>
>> Thanks
>> Sharan
>>
>> On 2018-01-14 12:33, "Sharan Foga"<sh...@apache.org> wrote:
>>>
>>> Excellent news Taher!
>>>
>>> Thanks very much for your effort on this. I'll aim to try it out this
>>> week and come back with any feedback.
>>>
>>> Thanks
>>> Sharan
>>>
>>> On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com> wrote:
>>>>
>>>> Hello everyone,
>>>>
>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>> have a small patch in [1] that provides the PoC for integrating
>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>> instructions on how to run it. Essentially, this allows you to create
>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>> directory and putting files inside.
>>>>
>>>> This solution is flexible and allows us to build bigger designs on top
>>>> of it. Please review it and tell me if you like the general design.
>>>>
>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>
>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>> <sl...@gmail.com> wrote:
>>>>>
>>>>> Hello Folks,
>>>>>
>>>>> We've had this discussion multiple times in the past, but I think I
>>>>> have a more concrete idea this time for solving this problem. In the
>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>> the best way to write and distribute documentation, and I think most
>>>>> of that is applicable to OFBiz.
>>>>>
>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>
>>>>> - The documentation language to use is Asciidoc
>>>>> - The documentation tool is Asciidoctor
>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>> plugin (not the OFBiz framework or anything else).
>>>>> - The only place where we write documentation is inside the code base
>>>>> - Every component contains its own documentation
>>>>> - General documentation goes to either a standalone directory or a
>>>>> generic component like common or base
>>>>> - As much as possible, documentation files are small and focused on
>>>>> one topic. And then other longer documents are constructed from these
>>>>> snippets of documentation.
>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>> help system, instead it just renders generated HTML.
>>>>>
>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>> neat that you can sprinkle variables all around in your document so
>>>>> that update is no longer a painful grepping process.
>>>>>
>>>>> Would love to hear your thoughts on this.
>>>>>
>>>>> Cheers,
>>>>>
>>>>> Taher Alkhateeb
>
>

Re: Listing All Menu Items

[Craig Parker <cr...@fossfolks.com>]

This is kind of what I'm looking for. Thanks. I think I can grab what I 
need now that I from about those files. I was hoping to make a "world 
atlas" of OFBiz, mostly to keep track of what is even out there (I 
haven't nearly been to all of it) and then down the road I hope to use 
some form of it, maybe as part of a larger PHP app, on my end to keep 
track of which end users have received training on which applications.

I was also trying to find a way to get the list automatically. I think 
that with Deepak's latest reply I can write a short shell script that 
will grab at least the top two levels and stick them into a format I can 
use, then down the road I can just run it again if the menus have 
changed. I've done it manually once, when creating a Wordpress theme 
menu that matched the menu layout in the OFBiz Tomahawk theme, and just 
didn't want to go through that whole process by hand again.


On 03/13/2018 02:18 AM, Deepak Dixit wrote:
> Hi Craig,
>
> Main menu item rendered through webapp not from component. A component can
> have multiple webapp. Ex.
>
> https://svn.apache.org/repos/asf/ofbiz/ofbiz-framework/trunk/applications/accounting/ofbiz-component.xml
>
>
> All webapp will be display by defuaut as menu item, if app-bar-display is
> set false it will not display as menu item.
> https://svn.apache.org/repos/asf/ofbiz/ofbiz-plugins/trunk/ecommerce/ofbiz-component.xml
>
>
> And sub-menu items display from Decorator, We can set secondary menu at
> decorator level
>
> <set field="applicationMenuName" value="OrderAppBar" global="true"/>
> <set field="applicationMenuLocation"
> value="component://order/widget/ordermgr/OrderMenus.xml"
> global="true"/>
>
>   MenuFactory.getMenuFromLocation method render these sub-menu items.
> Please refer
> https://svn.apache.org/repos/asf/ofbiz/ofbiz-framework/trunk/themes/tomahawk/template/AppBarOpen.ftl
>
>
> Thanks & Regards
> --
> Deepak Dixit
> www.hotwaxsystems.com
> www.hotwax.co
>
> On Tue, Mar 13, 2018 at 1:30 AM, Craig Parker <cr...@fossfolks.com> wrote:
>
>> I'm not a dev, so a lot of what you had me read wasn't clear. I am
>> familiar with MySQL though. These menu "sub items" aren't listed in the db
>> anywhere? I'm looking manually now in my servers information_schema db, but
>> if you know how to save me looking through a gazillion column names, I'm
>> all ears. :) If you can't, no biggie. I'd just hate to look all this time
>> and find out in the end that they're not there.
>>
>>
>> On 03/12/2018 01:47 PM, Deepak Dixit wrote:
>>
>>> Hi Craig,
>>>
>>> Please have a look at LoginWorker.getAppBarWebInfos and ComponentConfig.
>>> getAppBarWebInfos method.
>>> For reference you can have a look at themes/flatgrey/template/AppBar.ftl
>>>
>>> Thanks & Regards
>>> --
>>> Deepak Dixit
>>> www.hotwaxsystems.com
>>> www.hotwax.co
>>>
>>> On Mon, Mar 12, 2018 at 9:56 PM, Craig Parker <cr...@fossfolks.com>
>>> wrote:
>>>
>>> I'm running a clean slate install on MySQL, and trying to locate the main
>>>> OFBiz menu. Looks like there's a db named ofbiztenant with a table called
>>>> COMPONENT, and that appears to have at least the top level menu items.
>>>> Where are the others?
>>>>
>>>> Nothing official, but I'm trying to make a spreadsheet or something I can
>>>> print out for myself so that I can keep track of things going on in each
>>>> part of the software. I don't see the big picture yet, and I'm hoping
>>>> this
>>>> might help. :)
>>>>
>>>>

Re: Listing All Menu Items

[Rajesh Mallah <ma...@gmail.com>]

Hi Deepak ,

I guess you suggested the below:

<#assign displayApps =
Static["org.apache.ofbiz.webapp.control.LoginWorker"].*getAppBarWebInfos*(security,
userLogin, ofbizServerName, "*main*")>
<#assign displaySecondaryApps =
Static["org.apache.ofbiz.webapp.control.LoginWorker"].*getAppBarWebInfos*(security,
userLogin, ofbizServerName, "*secondary*")>


Are there entities that back *getAppBarWebInfos *?

I guess that would help .


regds
mallah.


On Tue, Mar 13, 2018 at 7:49 AM, Paul Foxworthy <pa...@cohsoft.com.au> wrote:

> Hi Craig,
>
> The major menu items correspond to major entities in the data model (Party,
> Product, Facility and so on). But many of the menu items are verbs and the
> entities are nouns.
>
> To explore the data model:
>
> Read the Data Model Resource Books, especially volume 1.
> https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Related+Books#
> OFBizRelatedBooks-TheDataModelResourceBook,Volumes1,2&3
>   http://isbn.nu/9781118082324
>
> Download the Big Book of Apache OFBiz Data Model from
> https://cwiki.apache.org/confluence/display/OFBIZ/Data+Model+Diagrams
>
> Use the Web Tools to explore the entities and the data. On the demo site,
> start at https://demo-trunk.ofbiz.apache.org/webtools/control/entitymaint
> .
>
> Cheers
>
> Paul Foxworthy
>
>
> On 13 March 2018 at 07:00, Craig Parker <cr...@fossfolks.com> wrote:
>
> > I'm not a dev, so a lot of what you had me read wasn't clear. I am
> > familiar with MySQL though. These menu "sub items" aren't listed in the
> db
> > anywhere? I'm looking manually now in my servers information_schema db,
> but
> > if you know how to save me looking through a gazillion column names, I'm
> > all ears. :) If you can't, no biggie. I'd just hate to look all this time
> > and find out in the end that they're not there.
> >
> >
> >
> > On 03/12/2018 01:47 PM, Deepak Dixit wrote:
> >
> >> Hi Craig,
> >>
> >> Please have a look at LoginWorker.getAppBarWebInfos and ComponentConfig.
> >> getAppBarWebInfos method.
> >> For reference you can have a look at themes/flatgrey/template/
> AppBar.ftl
> >>
> >> Thanks & Regards
> >> --
> >> Deepak Dixit
> >> www.hotwaxsystems.com
> >> www.hotwax.co
> >>
> >> On Mon, Mar 12, 2018 at 9:56 PM, Craig Parker <cr...@fossfolks.com>
> >> wrote:
> >>
> >> I'm running a clean slate install on MySQL, and trying to locate the
> main
> >>> OFBiz menu. Looks like there's a db named ofbiztenant with a table
> called
> >>> COMPONENT, and that appears to have at least the top level menu items.
> >>> Where are the others?
> >>>
> >>> Nothing official, but I'm trying to make a spreadsheet or something I
> can
> >>> print out for myself so that I can keep track of things going on in
> each
> >>> part of the software. I don't see the big picture yet, and I'm hoping
> >>> this
> >>> might help. :)
> >>>
> >>>
> >
>
>
> --
> Coherent Software Australia Pty Ltd
> PO Box 2773
> Cheltenham Vic 3192
> Australia
>
> Phone: +61 3 9585 6788
> Web: http://www.coherentsoftware.com.au/
> Email: info@coherentsoftware.com.au
>

Re: Listing All Menu Items

[Paul Foxworthy <pa...@cohsoft.com.au>]

Hi Craig,

The major menu items correspond to major entities in the data model (Party,
Product, Facility and so on). But many of the menu items are verbs and the
entities are nouns.

To explore the data model:

Read the Data Model Resource Books, especially volume 1.
https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Related+Books#OFBizRelatedBooks-TheDataModelResourceBook,Volumes1,2&3
  http://isbn.nu/9781118082324

Download the Big Book of Apache OFBiz Data Model from
https://cwiki.apache.org/confluence/display/OFBIZ/Data+Model+Diagrams

Use the Web Tools to explore the entities and the data. On the demo site,
start at https://demo-trunk.ofbiz.apache.org/webtools/control/entitymaint .

Cheers

Paul Foxworthy


On 13 March 2018 at 07:00, Craig Parker <cr...@fossfolks.com> wrote:

> I'm not a dev, so a lot of what you had me read wasn't clear. I am
> familiar with MySQL though. These menu "sub items" aren't listed in the db
> anywhere? I'm looking manually now in my servers information_schema db, but
> if you know how to save me looking through a gazillion column names, I'm
> all ears. :) If you can't, no biggie. I'd just hate to look all this time
> and find out in the end that they're not there.
>
>
>
> On 03/12/2018 01:47 PM, Deepak Dixit wrote:
>
>> Hi Craig,
>>
>> Please have a look at LoginWorker.getAppBarWebInfos and ComponentConfig.
>> getAppBarWebInfos method.
>> For reference you can have a look at themes/flatgrey/template/AppBar.ftl
>>
>> Thanks & Regards
>> --
>> Deepak Dixit
>> www.hotwaxsystems.com
>> www.hotwax.co
>>
>> On Mon, Mar 12, 2018 at 9:56 PM, Craig Parker <cr...@fossfolks.com>
>> wrote:
>>
>> I'm running a clean slate install on MySQL, and trying to locate the main
>>> OFBiz menu. Looks like there's a db named ofbiztenant with a table called
>>> COMPONENT, and that appears to have at least the top level menu items.
>>> Where are the others?
>>>
>>> Nothing official, but I'm trying to make a spreadsheet or something I can
>>> print out for myself so that I can keep track of things going on in each
>>> part of the software. I don't see the big picture yet, and I'm hoping
>>> this
>>> might help. :)
>>>
>>>
>


-- 
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Australia

Phone: +61 3 9585 6788
Web: http://www.coherentsoftware.com.au/
Email: info@coherentsoftware.com.au

Re: Listing All Menu Items

[Deepak Dixit <de...@hotwaxsystems.com>]

Hi Craig,

Main menu item rendered through webapp not from component. A component can
have multiple webapp. Ex.

https://svn.apache.org/repos/asf/ofbiz/ofbiz-framework/trunk/applications/accounting/ofbiz-component.xml


All webapp will be display by defuaut as menu item, if app-bar-display is
set false it will not display as menu item.
https://svn.apache.org/repos/asf/ofbiz/ofbiz-plugins/trunk/ecommerce/ofbiz-component.xml


And sub-menu items display from Decorator, We can set secondary menu at
decorator level

<set field="applicationMenuName" value="OrderAppBar" global="true"/>
<set field="applicationMenuLocation"
value="component://order/widget/ordermgr/OrderMenus.xml"
global="true"/>

 MenuFactory.getMenuFromLocation method render these sub-menu items.
Please refer
https://svn.apache.org/repos/asf/ofbiz/ofbiz-framework/trunk/themes/tomahawk/template/AppBarOpen.ftl


Thanks & Regards
--
Deepak Dixit
www.hotwaxsystems.com
www.hotwax.co

On Tue, Mar 13, 2018 at 1:30 AM, Craig Parker <cr...@fossfolks.com> wrote:

> I'm not a dev, so a lot of what you had me read wasn't clear. I am
> familiar with MySQL though. These menu "sub items" aren't listed in the db
> anywhere? I'm looking manually now in my servers information_schema db, but
> if you know how to save me looking through a gazillion column names, I'm
> all ears. :) If you can't, no biggie. I'd just hate to look all this time
> and find out in the end that they're not there.
>
>
> On 03/12/2018 01:47 PM, Deepak Dixit wrote:
>
>> Hi Craig,
>>
>> Please have a look at LoginWorker.getAppBarWebInfos and ComponentConfig.
>> getAppBarWebInfos method.
>> For reference you can have a look at themes/flatgrey/template/AppBar.ftl
>>
>> Thanks & Regards
>> --
>> Deepak Dixit
>> www.hotwaxsystems.com
>> www.hotwax.co
>>
>> On Mon, Mar 12, 2018 at 9:56 PM, Craig Parker <cr...@fossfolks.com>
>> wrote:
>>
>> I'm running a clean slate install on MySQL, and trying to locate the main
>>> OFBiz menu. Looks like there's a db named ofbiztenant with a table called
>>> COMPONENT, and that appears to have at least the top level menu items.
>>> Where are the others?
>>>
>>> Nothing official, but I'm trying to make a spreadsheet or something I can
>>> print out for myself so that I can keep track of things going on in each
>>> part of the software. I don't see the big picture yet, and I'm hoping
>>> this
>>> might help. :)
>>>
>>>
>

Re: Listing All Menu Items

[Craig Parker <cr...@fossfolks.com>]

I'm not a dev, so a lot of what you had me read wasn't clear. I am 
familiar with MySQL though. These menu "sub items" aren't listed in the 
db anywhere? I'm looking manually now in my servers information_schema 
db, but if you know how to save me looking through a gazillion column 
names, I'm all ears. :) If you can't, no biggie. I'd just hate to look 
all this time and find out in the end that they're not there.


On 03/12/2018 01:47 PM, Deepak Dixit wrote:
> Hi Craig,
>
> Please have a look at LoginWorker.getAppBarWebInfos and ComponentConfig.
> getAppBarWebInfos method.
> For reference you can have a look at themes/flatgrey/template/AppBar.ftl
>
> Thanks & Regards
> --
> Deepak Dixit
> www.hotwaxsystems.com
> www.hotwax.co
>
> On Mon, Mar 12, 2018 at 9:56 PM, Craig Parker <cr...@fossfolks.com> wrote:
>
>> I'm running a clean slate install on MySQL, and trying to locate the main
>> OFBiz menu. Looks like there's a db named ofbiztenant with a table called
>> COMPONENT, and that appears to have at least the top level menu items.
>> Where are the others?
>>
>> Nothing official, but I'm trying to make a spreadsheet or something I can
>> print out for myself so that I can keep track of things going on in each
>> part of the software. I don't see the big picture yet, and I'm hoping this
>> might help. :)
>>

Re: Listing All Menu Items

[Deepak Dixit <de...@hotwaxsystems.com>]

Hi Craig,

Please have a look at LoginWorker.getAppBarWebInfos and ComponentConfig.
getAppBarWebInfos method.
For reference you can have a look at themes/flatgrey/template/AppBar.ftl

Thanks & Regards
--
Deepak Dixit
www.hotwaxsystems.com
www.hotwax.co

On Mon, Mar 12, 2018 at 9:56 PM, Craig Parker <cr...@fossfolks.com> wrote:

> I'm running a clean slate install on MySQL, and trying to locate the main
> OFBiz menu. Looks like there's a db named ofbiztenant with a table called
> COMPONENT, and that appears to have at least the top level menu items.
> Where are the others?
>
> Nothing official, but I'm trying to make a spreadsheet or something I can
> print out for myself so that I can keep track of things going on in each
> part of the software. I don't see the big picture yet, and I'm hoping this
> might help. :)
>

Listing All Menu Items

[Craig Parker <cr...@fossfolks.com>]

I'm running a clean slate install on MySQL, and trying to locate the 
main OFBiz menu. Looks like there's a db named ofbiztenant with a table 
called COMPONENT, and that appears to have at least the top level menu 
items. Where are the others?

Nothing official, but I'm trying to make a spreadsheet or something I 
can print out for myself so that I can keep track of things going on in 
each part of the software. I don't see the big picture yet, and I'm 
hoping this might help. :)

Re: [Discussion] documentation framework for OFBiz

[Michael Brohl <mi...@ecomify.de>]

If the asciidoctor plugin provides no smarter way, I think this would be ok.

The documentation generation process is fast (at least with the few 
pages we have) so this should be no problem.

Thanks,

Michael


Am 12.03.18 um 16:38 schrieb Taher Alkhateeb:
> Maybe one way to accomplish this is to delete and regenerate every
> time. What do you think of that?
>
> On Mon, Mar 12, 2018 at 12:04 PM, Michael Brohl
> <mi...@ecomify.de> wrote:
>> Hi Taher,
>>
>> I worked on the documentation over the weekend.
>>
>> It would be very nice if the documentation gets updated even if the main
>> document has not changed. If you change only included documents, the change
>> does not go into the main document.
>>
>> I briefly searched for a configuration parameter but did not find any.
>>
>> Best regards,
>>
>> Michael
>>
>>
>> Am 24.02.18 um 15:44 schrieb Michael Brohl:
>>> I have tried Taher's latest patch and it is working great for me. I used
>>> Intellij Idea with the Asciidoc Plugin.
>>>
>>>
>>> Differently from Olivier's observation, the main developer-manual ist
>>> updated when I make a change in developer-manual.adoc. Both html and pdf
>>> include the change.
>>>
>>> It is not updated when I only change an included document like
>>> accounting.adoc. I think it would be good to recreate all files if they have
>>> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not
>>> be changed even if it is rewritten so it should be no problem.
>>>
>>> I think this is a good starting point, more pints might come up if we use
>>> it more intensely.
>>>
>>> Thanks,
>>>
>>> Michael
>>>
>>>
>>> Am 21.02.18 um 14:08 schrieb Olivier Heintz:
>>>> Thank you for the work, Taher
>>>>
>>>> I have played with it and merge with my tests.
>>>> Currently, I have start from Accounting_Agreement, convert from docbook
>>>> and update and
>>>> test renderer by both your gradle task and by AsciidocFx html button
>>>>
>>>> With a lot of include, result html file would be very large and in some
>>>> case it will be good to be able to put a link in place
>>>> of include. Currenlty the generateOfbizDocumentation task doesn't
>>>> generate file for doc in component even if the adoc file is
>>>> not in the _include directory.
>>>>
>>>> Just for information: With AsciidocFx (I have understood it use
>>>> asciidoctor for generate html file, but I'm not sure)
>>>> it's not necessary to say include file is in _include directory, it read
>>>> both in the current directory and in the _include one.
>>>> The generateOfbizDocumentation task doesn't use the same rule, we should
>>>> say explicitly it's in the _include directory.
>>>>
>>>> The main "malfunction" of the generateOfbizDocumentation task is that it
>>>> not re-generate the html file if it already exist
>>>> even if the main adoc file was modified. So it's needed to remove it
>>>> manually before call generateOfbizDocumentation.
>>>>
>>>> Thank you for your usage of leveloffset, it's generated by docbook
>>>> conversion, but now I understand how it works ;-)
>>>>
>>>>
>>>> Olivier
>>>>
>>>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit :
>>>>> Hello documentation team and everyone
>>>>>
>>>>> I have created a slightly modified design of the documentation
>>>>> framework with some sample contents in [1]. I highlight the changes
>>>>> below:
>>>>> - Created a new top-level directory called "docs/asciidoc". The reason
>>>>> is so that we have more than one possible manual.
>>>>> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
>>>>> - Created "Apache OFBiz Developer Manual" in
>>>>> docs/asciidoc/developer-manual.adoc
>>>>> - Created a sample document in the accounting component to show how
>>>>> documents are linked together.
>>>>> - Used a special directive called "leveloffset" in the include
>>>>> directive. This directive shifts the headers of the included document
>>>>> (H2 becomes H3, and so on) so that sub-sections can be published
>>>>> separately.
>>>>> - Created a task called generateOfbizDocumentation to generate the
>>>>> documentation (both PDF and HTML) for framework + core apps
>>>>> - Created a task called generatePluginDocumentation
>>>>> -PpluginId=whatever to generate the documentation for a single plugin.
>>>>>
>>>>> That's it. It's simple, easy to understand and I think you might like
>>>>> it. Any feedback is welcome, and I'll talk to you soon over Skype.
>>>>>
>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>
>>>>> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
>>>>>> Hi Taher
>>>>>>
>>>>>> I think a documentation team would be a great idea. There are people
>>>>>> that have indicated that they'd like to help out with documentation tasks on
>>>>>> the user list so that is where I'd recruit some people from. As long as
>>>>>> people know what they need to do to create the patches then it will become a
>>>>>> funnel process of getting it committed.
>>>>>>
>>>>>> We need a plan to consolidate the information sitting in the wiki and
>>>>>> getting it put into the documentation framework (and this work will then
>>>>>> significantly clear up the wiki!).
>>>>>>
>>>>>> My availability is pretty bad this week so hope to pick this up again
>>>>>> or start the recruitment campaign next week :-)
>>>>>>
>>>>>> Thanks
>>>>>> Sharan
>>>>>>
>>>>>> On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com>
>>>>>> wrote:
>>>>>>> Like Michael I think it is also a minor point. The reason I chose this
>>>>>>> structure is because it is the default one for asciidoctor and is
>>>>>>> flexible
>>>>>>> for the future, so Paul also makes a good point. Any structure is fine
>>>>>>> by
>>>>>>> me, the real important work is getting the documentation right which
>>>>>>> is
>>>>>>> very exciting to me.
>>>>>>>
>>>>>>> I will create a patch soon for a base level structure and publishing
>>>>>>> options for both HTML and PDF. It would be fantastic if we can unify
>>>>>>> _all_
>>>>>>> of our documentation here including stuff currently in the wiki. This
>>>>>>> way
>>>>>>> any changes to code are reflected (probably in the same commit) with
>>>>>>> the
>>>>>>> relevant documentation.
>>>>>>>
>>>>>>> I think we should start to consider maybe forming a team willing to
>>>>>>> help.
>>>>>>> This is a big, but extremely important thing to have. If we do this
>>>>>>> right
>>>>>>> then I think adoption rates would increase and our community would get
>>>>>>> larger.
>>>>>>>
>>>>>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de>
>>>>>>> wrote:
>>>>>>>
>>>>>>> Hi Paul,
>>>>>>>
>>>>>>> this is only a minor point for me, it just saves one folder/structure
>>>>>>> level.
>>>>>>>
>>>>>>> If we want to stay open for other documentation frameworks in the
>>>>>>> future,
>>>>>>> it might be better to keep the proposed structure.
>>>>>>>
>>>>>>> Best regards,
>>>>>>>
>>>>>>> Michael
>>>>>>>
>>>>>>>
>>>>>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>>>>>>>
>>>>>>> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de>
>>>>>>> wrote:
>>>>>>>>
>>>>>>>> with a small modification: I don't think we'll need a two-folder
>>>>>>>> structure
>>>>>>>>> /docs/asciidoc, only /docs should be sufficient, no?
>>>>>>>>>
>>>>>>>>> Hi Michael,
>>>>>>>> We have streamlined the build system in other places by having
>>>>>>>> folders for
>>>>>>>> the source language: groovyScripts, minilang, src/main/java .
>>>>>>>>
>>>>>>>> It means Groovy and other build tools can have default rules for what
>>>>>>>> to do
>>>>>>>> with the contents of a language folder, and allows for the
>>>>>>>> possibility of
>>>>>>>> other languages in future if necessary.
>>>>>>>>
>>>>>>>> The extra layer is only a minor nuisance. I think I'd prefer to keep
>>>>>>>> it.
>>>>>>>> What do you see as the disadvantages?
>>>>>>>>
>>>>>>>> Cheers
>>>>>>>>
>>>>>>>> Paul Foxworthy
>>>>>>>>
>>>>>>>>
>>>
>>

Re: [Discussion] documentation framework for OFBiz

[Sharan Foga <sh...@apache.org>]

On 2018/03/13 16:37:31, Taher Alkhateeb <sl...@gmail.com> wrote: 
> Hey guys, feature implemented in r1826656. Now both plugins and ofbiz
> manual will delete before re-generating their artifacts. I believe
> this will solve the problem and I think we won't have a big problem
> with performance, and probably won't be until we reach maybe thousands
> of documents.
> 
> By the way, may I also recommend that we minimize the number of
> documents in the beginning. So instead of creating new files, just
> create new headers, and split the file later when it gets too big.
> This way we do not overly complicate the design unless it makes sense.

Good point and agreed.  Let's get some content in and see how it evolves.

Thanks
Sharan

> 
> On Mon, Mar 12, 2018 at 6:44 PM, Sharan Foga <sh...@apache.org> wrote:
> > Hi  Taher
> >
> > Manually deleting and regenerating is what I've been doing :-)  so it could be a start. We are evolving - right?  We might need to look at it again if it becomes an issue as we fill up the content..
> >
> > Thanks
> > Sharan
> >
> >
> > On 2018/03/12 15:38:44, Taher Alkhateeb <sl...@gmail.com> wrote:
> >> Maybe one way to accomplish this is to delete and regenerate every
> >> time. What do you think of that?
> >>
> >> On Mon, Mar 12, 2018 at 12:04 PM, Michael Brohl
> >> <mi...@ecomify.de> wrote:
> >> > Hi Taher,
> >> >
> >> > I worked on the documentation over the weekend.
> >> >
> >> > It would be very nice if the documentation gets updated even if the main
> >> > document has not changed. If you change only included documents, the change
> >> > does not go into the main document.
> >> >
> >> > I briefly searched for a configuration parameter but did not find any.
> >> >
> >> > Best regards,
> >> >
> >> > Michael
> >> >
> >> >
> >> > Am 24.02.18 um 15:44 schrieb Michael Brohl:
> >> >>
> >> >> I have tried Taher's latest patch and it is working great for me. I used
> >> >> Intellij Idea with the Asciidoc Plugin.
> >> >>
> >> >>
> >> >> Differently from Olivier's observation, the main developer-manual ist
> >> >> updated when I make a change in developer-manual.adoc. Both html and pdf
> >> >> include the change.
> >> >>
> >> >> It is not updated when I only change an included document like
> >> >> accounting.adoc. I think it would be good to recreate all files if they have
> >> >> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not
> >> >> be changed even if it is rewritten so it should be no problem.
> >> >>
> >> >> I think this is a good starting point, more pints might come up if we use
> >> >> it more intensely.
> >> >>
> >> >> Thanks,
> >> >>
> >> >> Michael
> >> >>
> >> >>
> >> >> Am 21.02.18 um 14:08 schrieb Olivier Heintz:
> >> >>>
> >> >>> Thank you for the work, Taher
> >> >>>
> >> >>> I have played with it and merge with my tests.
> >> >>> Currently, I have start from Accounting_Agreement, convert from docbook
> >> >>> and update and
> >> >>> test renderer by both your gradle task and by AsciidocFx html button
> >> >>>
> >> >>> With a lot of include, result html file would be very large and in some
> >> >>> case it will be good to be able to put a link in place
> >> >>> of include. Currenlty the generateOfbizDocumentation task doesn't
> >> >>> generate file for doc in component even if the adoc file is
> >> >>> not in the _include directory.
> >> >>>
> >> >>> Just for information: With AsciidocFx (I have understood it use
> >> >>> asciidoctor for generate html file, but I'm not sure)
> >> >>> it's not necessary to say include file is in _include directory, it read
> >> >>> both in the current directory and in the _include one.
> >> >>> The generateOfbizDocumentation task doesn't use the same rule, we should
> >> >>> say explicitly it's in the _include directory.
> >> >>>
> >> >>> The main "malfunction" of the generateOfbizDocumentation task is that it
> >> >>> not re-generate the html file if it already exist
> >> >>> even if the main adoc file was modified. So it's needed to remove it
> >> >>> manually before call generateOfbizDocumentation.
> >> >>>
> >> >>> Thank you for your usage of leveloffset, it's generated by docbook
> >> >>> conversion, but now I understand how it works ;-)
> >> >>>
> >> >>>
> >> >>> Olivier
> >> >>>
> >> >>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit :
> >> >>>>
> >> >>>> Hello documentation team and everyone
> >> >>>>
> >> >>>> I have created a slightly modified design of the documentation
> >> >>>> framework with some sample contents in [1]. I highlight the changes
> >> >>>> below:
> >> >>>> - Created a new top-level directory called "docs/asciidoc". The reason
> >> >>>> is so that we have more than one possible manual.
> >> >>>> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
> >> >>>> - Created "Apache OFBiz Developer Manual" in
> >> >>>> docs/asciidoc/developer-manual.adoc
> >> >>>> - Created a sample document in the accounting component to show how
> >> >>>> documents are linked together.
> >> >>>> - Used a special directive called "leveloffset" in the include
> >> >>>> directive. This directive shifts the headers of the included document
> >> >>>> (H2 becomes H3, and so on) so that sub-sections can be published
> >> >>>> separately.
> >> >>>> - Created a task called generateOfbizDocumentation to generate the
> >> >>>> documentation (both PDF and HTML) for framework + core apps
> >> >>>> - Created a task called generatePluginDocumentation
> >> >>>> -PpluginId=whatever to generate the documentation for a single plugin.
> >> >>>>
> >> >>>> That's it. It's simple, easy to understand and I think you might like
> >> >>>> it. Any feedback is welcome, and I'll talk to you soon over Skype.
> >> >>>>
> >> >>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
> >> >>>>
> >> >>>> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
> >> >>>>>
> >> >>>>> Hi Taher
> >> >>>>>
> >> >>>>> I think a documentation team would be a great idea. There are people
> >> >>>>> that have indicated that they'd like to help out with documentation tasks on
> >> >>>>> the user list so that is where I'd recruit some people from. As long as
> >> >>>>> people know what they need to do to create the patches then it will become a
> >> >>>>> funnel process of getting it committed.
> >> >>>>>
> >> >>>>> We need a plan to consolidate the information sitting in the wiki and
> >> >>>>> getting it put into the documentation framework (and this work will then
> >> >>>>> significantly clear up the wiki!).
> >> >>>>>
> >> >>>>> My availability is pretty bad this week so hope to pick this up again
> >> >>>>> or start the recruitment campaign next week :-)
> >> >>>>>
> >> >>>>> Thanks
> >> >>>>> Sharan
> >> >>>>>
> >> >>>>> On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com>
> >> >>>>> wrote:
> >> >>>>>>
> >> >>>>>> Like Michael I think it is also a minor point. The reason I chose this
> >> >>>>>> structure is because it is the default one for asciidoctor and is
> >> >>>>>> flexible
> >> >>>>>> for the future, so Paul also makes a good point. Any structure is fine
> >> >>>>>> by
> >> >>>>>> me, the real important work is getting the documentation right which
> >> >>>>>> is
> >> >>>>>> very exciting to me.
> >> >>>>>>
> >> >>>>>> I will create a patch soon for a base level structure and publishing
> >> >>>>>> options for both HTML and PDF. It would be fantastic if we can unify
> >> >>>>>> _all_
> >> >>>>>> of our documentation here including stuff currently in the wiki. This
> >> >>>>>> way
> >> >>>>>> any changes to code are reflected (probably in the same commit) with
> >> >>>>>> the
> >> >>>>>> relevant documentation.
> >> >>>>>>
> >> >>>>>> I think we should start to consider maybe forming a team willing to
> >> >>>>>> help.
> >> >>>>>> This is a big, but extremely important thing to have. If we do this
> >> >>>>>> right
> >> >>>>>> then I think adoption rates would increase and our community would get
> >> >>>>>> larger.
> >> >>>>>>
> >> >>>>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de>
> >> >>>>>> wrote:
> >> >>>>>>
> >> >>>>>> Hi Paul,
> >> >>>>>>
> >> >>>>>> this is only a minor point for me, it just saves one folder/structure
> >> >>>>>> level.
> >> >>>>>>
> >> >>>>>> If we want to stay open for other documentation frameworks in the
> >> >>>>>> future,
> >> >>>>>> it might be better to keep the proposed structure.
> >> >>>>>>
> >> >>>>>> Best regards,
> >> >>>>>>
> >> >>>>>> Michael
> >> >>>>>>
> >> >>>>>>
> >> >>>>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
> >> >>>>>>
> >> >>>>>> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de>
> >> >>>>>> wrote:
> >> >>>>>>>
> >> >>>>>>>
> >> >>>>>>> with a small modification: I don't think we'll need a two-folder
> >> >>>>>>> structure
> >> >>>>>>>>
> >> >>>>>>>> /docs/asciidoc, only /docs should be sufficient, no?
> >> >>>>>>>>
> >> >>>>>>>> Hi Michael,
> >> >>>>>>>
> >> >>>>>>> We have streamlined the build system in other places by having
> >> >>>>>>> folders for
> >> >>>>>>> the source language: groovyScripts, minilang, src/main/java .
> >> >>>>>>>
> >> >>>>>>> It means Groovy and other build tools can have default rules for what
> >> >>>>>>> to do
> >> >>>>>>> with the contents of a language folder, and allows for the
> >> >>>>>>> possibility of
> >> >>>>>>> other languages in future if necessary.
> >> >>>>>>>
> >> >>>>>>> The extra layer is only a minor nuisance. I think I'd prefer to keep
> >> >>>>>>> it.
> >> >>>>>>> What do you see as the disadvantages?
> >> >>>>>>>
> >> >>>>>>> Cheers
> >> >>>>>>>
> >> >>>>>>> Paul Foxworthy
> >> >>>>>>>
> >> >>>>>>>
> >> >>
> >> >>
> >> >
> >> >
> >>
> 

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

Hey guys, feature implemented in r1826656. Now both plugins and ofbiz
manual will delete before re-generating their artifacts. I believe
this will solve the problem and I think we won't have a big problem
with performance, and probably won't be until we reach maybe thousands
of documents.

By the way, may I also recommend that we minimize the number of
documents in the beginning. So instead of creating new files, just
create new headers, and split the file later when it gets too big.
This way we do not overly complicate the design unless it makes sense.

On Mon, Mar 12, 2018 at 6:44 PM, Sharan Foga <sh...@apache.org> wrote:
> Hi  Taher
>
> Manually deleting and regenerating is what I've been doing :-)  so it could be a start. We are evolving - right?  We might need to look at it again if it becomes an issue as we fill up the content..
>
> Thanks
> Sharan
>
>
> On 2018/03/12 15:38:44, Taher Alkhateeb <sl...@gmail.com> wrote:
>> Maybe one way to accomplish this is to delete and regenerate every
>> time. What do you think of that?
>>
>> On Mon, Mar 12, 2018 at 12:04 PM, Michael Brohl
>> <mi...@ecomify.de> wrote:
>> > Hi Taher,
>> >
>> > I worked on the documentation over the weekend.
>> >
>> > It would be very nice if the documentation gets updated even if the main
>> > document has not changed. If you change only included documents, the change
>> > does not go into the main document.
>> >
>> > I briefly searched for a configuration parameter but did not find any.
>> >
>> > Best regards,
>> >
>> > Michael
>> >
>> >
>> > Am 24.02.18 um 15:44 schrieb Michael Brohl:
>> >>
>> >> I have tried Taher's latest patch and it is working great for me. I used
>> >> Intellij Idea with the Asciidoc Plugin.
>> >>
>> >>
>> >> Differently from Olivier's observation, the main developer-manual ist
>> >> updated when I make a change in developer-manual.adoc. Both html and pdf
>> >> include the change.
>> >>
>> >> It is not updated when I only change an included document like
>> >> accounting.adoc. I think it would be good to recreate all files if they have
>> >> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not
>> >> be changed even if it is rewritten so it should be no problem.
>> >>
>> >> I think this is a good starting point, more pints might come up if we use
>> >> it more intensely.
>> >>
>> >> Thanks,
>> >>
>> >> Michael
>> >>
>> >>
>> >> Am 21.02.18 um 14:08 schrieb Olivier Heintz:
>> >>>
>> >>> Thank you for the work, Taher
>> >>>
>> >>> I have played with it and merge with my tests.
>> >>> Currently, I have start from Accounting_Agreement, convert from docbook
>> >>> and update and
>> >>> test renderer by both your gradle task and by AsciidocFx html button
>> >>>
>> >>> With a lot of include, result html file would be very large and in some
>> >>> case it will be good to be able to put a link in place
>> >>> of include. Currenlty the generateOfbizDocumentation task doesn't
>> >>> generate file for doc in component even if the adoc file is
>> >>> not in the _include directory.
>> >>>
>> >>> Just for information: With AsciidocFx (I have understood it use
>> >>> asciidoctor for generate html file, but I'm not sure)
>> >>> it's not necessary to say include file is in _include directory, it read
>> >>> both in the current directory and in the _include one.
>> >>> The generateOfbizDocumentation task doesn't use the same rule, we should
>> >>> say explicitly it's in the _include directory.
>> >>>
>> >>> The main "malfunction" of the generateOfbizDocumentation task is that it
>> >>> not re-generate the html file if it already exist
>> >>> even if the main adoc file was modified. So it's needed to remove it
>> >>> manually before call generateOfbizDocumentation.
>> >>>
>> >>> Thank you for your usage of leveloffset, it's generated by docbook
>> >>> conversion, but now I understand how it works ;-)
>> >>>
>> >>>
>> >>> Olivier
>> >>>
>> >>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit :
>> >>>>
>> >>>> Hello documentation team and everyone
>> >>>>
>> >>>> I have created a slightly modified design of the documentation
>> >>>> framework with some sample contents in [1]. I highlight the changes
>> >>>> below:
>> >>>> - Created a new top-level directory called "docs/asciidoc". The reason
>> >>>> is so that we have more than one possible manual.
>> >>>> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
>> >>>> - Created "Apache OFBiz Developer Manual" in
>> >>>> docs/asciidoc/developer-manual.adoc
>> >>>> - Created a sample document in the accounting component to show how
>> >>>> documents are linked together.
>> >>>> - Used a special directive called "leveloffset" in the include
>> >>>> directive. This directive shifts the headers of the included document
>> >>>> (H2 becomes H3, and so on) so that sub-sections can be published
>> >>>> separately.
>> >>>> - Created a task called generateOfbizDocumentation to generate the
>> >>>> documentation (both PDF and HTML) for framework + core apps
>> >>>> - Created a task called generatePluginDocumentation
>> >>>> -PpluginId=whatever to generate the documentation for a single plugin.
>> >>>>
>> >>>> That's it. It's simple, easy to understand and I think you might like
>> >>>> it. Any feedback is welcome, and I'll talk to you soon over Skype.
>> >>>>
>> >>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>> >>>>
>> >>>> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
>> >>>>>
>> >>>>> Hi Taher
>> >>>>>
>> >>>>> I think a documentation team would be a great idea. There are people
>> >>>>> that have indicated that they'd like to help out with documentation tasks on
>> >>>>> the user list so that is where I'd recruit some people from. As long as
>> >>>>> people know what they need to do to create the patches then it will become a
>> >>>>> funnel process of getting it committed.
>> >>>>>
>> >>>>> We need a plan to consolidate the information sitting in the wiki and
>> >>>>> getting it put into the documentation framework (and this work will then
>> >>>>> significantly clear up the wiki!).
>> >>>>>
>> >>>>> My availability is pretty bad this week so hope to pick this up again
>> >>>>> or start the recruitment campaign next week :-)
>> >>>>>
>> >>>>> Thanks
>> >>>>> Sharan
>> >>>>>
>> >>>>> On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com>
>> >>>>> wrote:
>> >>>>>>
>> >>>>>> Like Michael I think it is also a minor point. The reason I chose this
>> >>>>>> structure is because it is the default one for asciidoctor and is
>> >>>>>> flexible
>> >>>>>> for the future, so Paul also makes a good point. Any structure is fine
>> >>>>>> by
>> >>>>>> me, the real important work is getting the documentation right which
>> >>>>>> is
>> >>>>>> very exciting to me.
>> >>>>>>
>> >>>>>> I will create a patch soon for a base level structure and publishing
>> >>>>>> options for both HTML and PDF. It would be fantastic if we can unify
>> >>>>>> _all_
>> >>>>>> of our documentation here including stuff currently in the wiki. This
>> >>>>>> way
>> >>>>>> any changes to code are reflected (probably in the same commit) with
>> >>>>>> the
>> >>>>>> relevant documentation.
>> >>>>>>
>> >>>>>> I think we should start to consider maybe forming a team willing to
>> >>>>>> help.
>> >>>>>> This is a big, but extremely important thing to have. If we do this
>> >>>>>> right
>> >>>>>> then I think adoption rates would increase and our community would get
>> >>>>>> larger.
>> >>>>>>
>> >>>>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de>
>> >>>>>> wrote:
>> >>>>>>
>> >>>>>> Hi Paul,
>> >>>>>>
>> >>>>>> this is only a minor point for me, it just saves one folder/structure
>> >>>>>> level.
>> >>>>>>
>> >>>>>> If we want to stay open for other documentation frameworks in the
>> >>>>>> future,
>> >>>>>> it might be better to keep the proposed structure.
>> >>>>>>
>> >>>>>> Best regards,
>> >>>>>>
>> >>>>>> Michael
>> >>>>>>
>> >>>>>>
>> >>>>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>> >>>>>>
>> >>>>>> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de>
>> >>>>>> wrote:
>> >>>>>>>
>> >>>>>>>
>> >>>>>>> with a small modification: I don't think we'll need a two-folder
>> >>>>>>> structure
>> >>>>>>>>
>> >>>>>>>> /docs/asciidoc, only /docs should be sufficient, no?
>> >>>>>>>>
>> >>>>>>>> Hi Michael,
>> >>>>>>>
>> >>>>>>> We have streamlined the build system in other places by having
>> >>>>>>> folders for
>> >>>>>>> the source language: groovyScripts, minilang, src/main/java .
>> >>>>>>>
>> >>>>>>> It means Groovy and other build tools can have default rules for what
>> >>>>>>> to do
>> >>>>>>> with the contents of a language folder, and allows for the
>> >>>>>>> possibility of
>> >>>>>>> other languages in future if necessary.
>> >>>>>>>
>> >>>>>>> The extra layer is only a minor nuisance. I think I'd prefer to keep
>> >>>>>>> it.
>> >>>>>>> What do you see as the disadvantages?
>> >>>>>>>
>> >>>>>>> Cheers
>> >>>>>>>
>> >>>>>>> Paul Foxworthy
>> >>>>>>>
>> >>>>>>>
>> >>
>> >>
>> >
>> >
>>

Re: [Discussion] documentation framework for OFBiz

[Sharan Foga <sh...@apache.org>]

Hi  Taher

Manually deleting and regenerating is what I've been doing :-)  so it could be a start. We are evolving - right?  We might need to look at it again if it becomes an issue as we fill up the content..

Thanks
Sharan


On 2018/03/12 15:38:44, Taher Alkhateeb <sl...@gmail.com> wrote: 
> Maybe one way to accomplish this is to delete and regenerate every
> time. What do you think of that?
> 
> On Mon, Mar 12, 2018 at 12:04 PM, Michael Brohl
> <mi...@ecomify.de> wrote:
> > Hi Taher,
> >
> > I worked on the documentation over the weekend.
> >
> > It would be very nice if the documentation gets updated even if the main
> > document has not changed. If you change only included documents, the change
> > does not go into the main document.
> >
> > I briefly searched for a configuration parameter but did not find any.
> >
> > Best regards,
> >
> > Michael
> >
> >
> > Am 24.02.18 um 15:44 schrieb Michael Brohl:
> >>
> >> I have tried Taher's latest patch and it is working great for me. I used
> >> Intellij Idea with the Asciidoc Plugin.
> >>
> >>
> >> Differently from Olivier's observation, the main developer-manual ist
> >> updated when I make a change in developer-manual.adoc. Both html and pdf
> >> include the change.
> >>
> >> It is not updated when I only change an included document like
> >> accounting.adoc. I think it would be good to recreate all files if they have
> >> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not
> >> be changed even if it is rewritten so it should be no problem.
> >>
> >> I think this is a good starting point, more pints might come up if we use
> >> it more intensely.
> >>
> >> Thanks,
> >>
> >> Michael
> >>
> >>
> >> Am 21.02.18 um 14:08 schrieb Olivier Heintz:
> >>>
> >>> Thank you for the work, Taher
> >>>
> >>> I have played with it and merge with my tests.
> >>> Currently, I have start from Accounting_Agreement, convert from docbook
> >>> and update and
> >>> test renderer by both your gradle task and by AsciidocFx html button
> >>>
> >>> With a lot of include, result html file would be very large and in some
> >>> case it will be good to be able to put a link in place
> >>> of include. Currenlty the generateOfbizDocumentation task doesn't
> >>> generate file for doc in component even if the adoc file is
> >>> not in the _include directory.
> >>>
> >>> Just for information: With AsciidocFx (I have understood it use
> >>> asciidoctor for generate html file, but I'm not sure)
> >>> it's not necessary to say include file is in _include directory, it read
> >>> both in the current directory and in the _include one.
> >>> The generateOfbizDocumentation task doesn't use the same rule, we should
> >>> say explicitly it's in the _include directory.
> >>>
> >>> The main "malfunction" of the generateOfbizDocumentation task is that it
> >>> not re-generate the html file if it already exist
> >>> even if the main adoc file was modified. So it's needed to remove it
> >>> manually before call generateOfbizDocumentation.
> >>>
> >>> Thank you for your usage of leveloffset, it's generated by docbook
> >>> conversion, but now I understand how it works ;-)
> >>>
> >>>
> >>> Olivier
> >>>
> >>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit :
> >>>>
> >>>> Hello documentation team and everyone
> >>>>
> >>>> I have created a slightly modified design of the documentation
> >>>> framework with some sample contents in [1]. I highlight the changes
> >>>> below:
> >>>> - Created a new top-level directory called "docs/asciidoc". The reason
> >>>> is so that we have more than one possible manual.
> >>>> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
> >>>> - Created "Apache OFBiz Developer Manual" in
> >>>> docs/asciidoc/developer-manual.adoc
> >>>> - Created a sample document in the accounting component to show how
> >>>> documents are linked together.
> >>>> - Used a special directive called "leveloffset" in the include
> >>>> directive. This directive shifts the headers of the included document
> >>>> (H2 becomes H3, and so on) so that sub-sections can be published
> >>>> separately.
> >>>> - Created a task called generateOfbizDocumentation to generate the
> >>>> documentation (both PDF and HTML) for framework + core apps
> >>>> - Created a task called generatePluginDocumentation
> >>>> -PpluginId=whatever to generate the documentation for a single plugin.
> >>>>
> >>>> That's it. It's simple, easy to understand and I think you might like
> >>>> it. Any feedback is welcome, and I'll talk to you soon over Skype.
> >>>>
> >>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
> >>>>
> >>>> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
> >>>>>
> >>>>> Hi Taher
> >>>>>
> >>>>> I think a documentation team would be a great idea. There are people
> >>>>> that have indicated that they'd like to help out with documentation tasks on
> >>>>> the user list so that is where I'd recruit some people from. As long as
> >>>>> people know what they need to do to create the patches then it will become a
> >>>>> funnel process of getting it committed.
> >>>>>
> >>>>> We need a plan to consolidate the information sitting in the wiki and
> >>>>> getting it put into the documentation framework (and this work will then
> >>>>> significantly clear up the wiki!).
> >>>>>
> >>>>> My availability is pretty bad this week so hope to pick this up again
> >>>>> or start the recruitment campaign next week :-)
> >>>>>
> >>>>> Thanks
> >>>>> Sharan
> >>>>>
> >>>>> On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com>
> >>>>> wrote:
> >>>>>>
> >>>>>> Like Michael I think it is also a minor point. The reason I chose this
> >>>>>> structure is because it is the default one for asciidoctor and is
> >>>>>> flexible
> >>>>>> for the future, so Paul also makes a good point. Any structure is fine
> >>>>>> by
> >>>>>> me, the real important work is getting the documentation right which
> >>>>>> is
> >>>>>> very exciting to me.
> >>>>>>
> >>>>>> I will create a patch soon for a base level structure and publishing
> >>>>>> options for both HTML and PDF. It would be fantastic if we can unify
> >>>>>> _all_
> >>>>>> of our documentation here including stuff currently in the wiki. This
> >>>>>> way
> >>>>>> any changes to code are reflected (probably in the same commit) with
> >>>>>> the
> >>>>>> relevant documentation.
> >>>>>>
> >>>>>> I think we should start to consider maybe forming a team willing to
> >>>>>> help.
> >>>>>> This is a big, but extremely important thing to have. If we do this
> >>>>>> right
> >>>>>> then I think adoption rates would increase and our community would get
> >>>>>> larger.
> >>>>>>
> >>>>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de>
> >>>>>> wrote:
> >>>>>>
> >>>>>> Hi Paul,
> >>>>>>
> >>>>>> this is only a minor point for me, it just saves one folder/structure
> >>>>>> level.
> >>>>>>
> >>>>>> If we want to stay open for other documentation frameworks in the
> >>>>>> future,
> >>>>>> it might be better to keep the proposed structure.
> >>>>>>
> >>>>>> Best regards,
> >>>>>>
> >>>>>> Michael
> >>>>>>
> >>>>>>
> >>>>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
> >>>>>>
> >>>>>> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de>
> >>>>>> wrote:
> >>>>>>>
> >>>>>>>
> >>>>>>> with a small modification: I don't think we'll need a two-folder
> >>>>>>> structure
> >>>>>>>>
> >>>>>>>> /docs/asciidoc, only /docs should be sufficient, no?
> >>>>>>>>
> >>>>>>>> Hi Michael,
> >>>>>>>
> >>>>>>> We have streamlined the build system in other places by having
> >>>>>>> folders for
> >>>>>>> the source language: groovyScripts, minilang, src/main/java .
> >>>>>>>
> >>>>>>> It means Groovy and other build tools can have default rules for what
> >>>>>>> to do
> >>>>>>> with the contents of a language folder, and allows for the
> >>>>>>> possibility of
> >>>>>>> other languages in future if necessary.
> >>>>>>>
> >>>>>>> The extra layer is only a minor nuisance. I think I'd prefer to keep
> >>>>>>> it.
> >>>>>>> What do you see as the disadvantages?
> >>>>>>>
> >>>>>>> Cheers
> >>>>>>>
> >>>>>>> Paul Foxworthy
> >>>>>>>
> >>>>>>>
> >>
> >>
> >
> >
> 

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

Maybe one way to accomplish this is to delete and regenerate every
time. What do you think of that?

On Mon, Mar 12, 2018 at 12:04 PM, Michael Brohl
<mi...@ecomify.de> wrote:
> Hi Taher,
>
> I worked on the documentation over the weekend.
>
> It would be very nice if the documentation gets updated even if the main
> document has not changed. If you change only included documents, the change
> does not go into the main document.
>
> I briefly searched for a configuration parameter but did not find any.
>
> Best regards,
>
> Michael
>
>
> Am 24.02.18 um 15:44 schrieb Michael Brohl:
>>
>> I have tried Taher's latest patch and it is working great for me. I used
>> Intellij Idea with the Asciidoc Plugin.
>>
>>
>> Differently from Olivier's observation, the main developer-manual ist
>> updated when I make a change in developer-manual.adoc. Both html and pdf
>> include the change.
>>
>> It is not updated when I only change an included document like
>> accounting.adoc. I think it would be good to recreate all files if they have
>> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not
>> be changed even if it is rewritten so it should be no problem.
>>
>> I think this is a good starting point, more pints might come up if we use
>> it more intensely.
>>
>> Thanks,
>>
>> Michael
>>
>>
>> Am 21.02.18 um 14:08 schrieb Olivier Heintz:
>>>
>>> Thank you for the work, Taher
>>>
>>> I have played with it and merge with my tests.
>>> Currently, I have start from Accounting_Agreement, convert from docbook
>>> and update and
>>> test renderer by both your gradle task and by AsciidocFx html button
>>>
>>> With a lot of include, result html file would be very large and in some
>>> case it will be good to be able to put a link in place
>>> of include. Currenlty the generateOfbizDocumentation task doesn't
>>> generate file for doc in component even if the adoc file is
>>> not in the _include directory.
>>>
>>> Just for information: With AsciidocFx (I have understood it use
>>> asciidoctor for generate html file, but I'm not sure)
>>> it's not necessary to say include file is in _include directory, it read
>>> both in the current directory and in the _include one.
>>> The generateOfbizDocumentation task doesn't use the same rule, we should
>>> say explicitly it's in the _include directory.
>>>
>>> The main "malfunction" of the generateOfbizDocumentation task is that it
>>> not re-generate the html file if it already exist
>>> even if the main adoc file was modified. So it's needed to remove it
>>> manually before call generateOfbizDocumentation.
>>>
>>> Thank you for your usage of leveloffset, it's generated by docbook
>>> conversion, but now I understand how it works ;-)
>>>
>>>
>>> Olivier
>>>
>>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit :
>>>>
>>>> Hello documentation team and everyone
>>>>
>>>> I have created a slightly modified design of the documentation
>>>> framework with some sample contents in [1]. I highlight the changes
>>>> below:
>>>> - Created a new top-level directory called "docs/asciidoc". The reason
>>>> is so that we have more than one possible manual.
>>>> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
>>>> - Created "Apache OFBiz Developer Manual" in
>>>> docs/asciidoc/developer-manual.adoc
>>>> - Created a sample document in the accounting component to show how
>>>> documents are linked together.
>>>> - Used a special directive called "leveloffset" in the include
>>>> directive. This directive shifts the headers of the included document
>>>> (H2 becomes H3, and so on) so that sub-sections can be published
>>>> separately.
>>>> - Created a task called generateOfbizDocumentation to generate the
>>>> documentation (both PDF and HTML) for framework + core apps
>>>> - Created a task called generatePluginDocumentation
>>>> -PpluginId=whatever to generate the documentation for a single plugin.
>>>>
>>>> That's it. It's simple, easy to understand and I think you might like
>>>> it. Any feedback is welcome, and I'll talk to you soon over Skype.
>>>>
>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>
>>>> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
>>>>>
>>>>> Hi Taher
>>>>>
>>>>> I think a documentation team would be a great idea. There are people
>>>>> that have indicated that they'd like to help out with documentation tasks on
>>>>> the user list so that is where I'd recruit some people from. As long as
>>>>> people know what they need to do to create the patches then it will become a
>>>>> funnel process of getting it committed.
>>>>>
>>>>> We need a plan to consolidate the information sitting in the wiki and
>>>>> getting it put into the documentation framework (and this work will then
>>>>> significantly clear up the wiki!).
>>>>>
>>>>> My availability is pretty bad this week so hope to pick this up again
>>>>> or start the recruitment campaign next week :-)
>>>>>
>>>>> Thanks
>>>>> Sharan
>>>>>
>>>>> On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com>
>>>>> wrote:
>>>>>>
>>>>>> Like Michael I think it is also a minor point. The reason I chose this
>>>>>> structure is because it is the default one for asciidoctor and is
>>>>>> flexible
>>>>>> for the future, so Paul also makes a good point. Any structure is fine
>>>>>> by
>>>>>> me, the real important work is getting the documentation right which
>>>>>> is
>>>>>> very exciting to me.
>>>>>>
>>>>>> I will create a patch soon for a base level structure and publishing
>>>>>> options for both HTML and PDF. It would be fantastic if we can unify
>>>>>> _all_
>>>>>> of our documentation here including stuff currently in the wiki. This
>>>>>> way
>>>>>> any changes to code are reflected (probably in the same commit) with
>>>>>> the
>>>>>> relevant documentation.
>>>>>>
>>>>>> I think we should start to consider maybe forming a team willing to
>>>>>> help.
>>>>>> This is a big, but extremely important thing to have. If we do this
>>>>>> right
>>>>>> then I think adoption rates would increase and our community would get
>>>>>> larger.
>>>>>>
>>>>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de>
>>>>>> wrote:
>>>>>>
>>>>>> Hi Paul,
>>>>>>
>>>>>> this is only a minor point for me, it just saves one folder/structure
>>>>>> level.
>>>>>>
>>>>>> If we want to stay open for other documentation frameworks in the
>>>>>> future,
>>>>>> it might be better to keep the proposed structure.
>>>>>>
>>>>>> Best regards,
>>>>>>
>>>>>> Michael
>>>>>>
>>>>>>
>>>>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>>>>>>
>>>>>> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de>
>>>>>> wrote:
>>>>>>>
>>>>>>>
>>>>>>> with a small modification: I don't think we'll need a two-folder
>>>>>>> structure
>>>>>>>>
>>>>>>>> /docs/asciidoc, only /docs should be sufficient, no?
>>>>>>>>
>>>>>>>> Hi Michael,
>>>>>>>
>>>>>>> We have streamlined the build system in other places by having
>>>>>>> folders for
>>>>>>> the source language: groovyScripts, minilang, src/main/java .
>>>>>>>
>>>>>>> It means Groovy and other build tools can have default rules for what
>>>>>>> to do
>>>>>>> with the contents of a language folder, and allows for the
>>>>>>> possibility of
>>>>>>> other languages in future if necessary.
>>>>>>>
>>>>>>> The extra layer is only a minor nuisance. I think I'd prefer to keep
>>>>>>> it.
>>>>>>> What do you see as the disadvantages?
>>>>>>>
>>>>>>> Cheers
>>>>>>>
>>>>>>> Paul Foxworthy
>>>>>>>
>>>>>>>
>>
>>
>
>

Re: [Discussion] documentation framework for OFBiz

[Michael Brohl <mi...@ecomify.de>]

Hi Taher,

I worked on the documentation over the weekend.

It would be very nice if the documentation gets updated even if the main 
document has not changed. If you change only included documents, the 
change does not go into the main document.

I briefly searched for a configuration parameter but did not find any.

Best regards,

Michael


Am 24.02.18 um 15:44 schrieb Michael Brohl:
> I have tried Taher's latest patch and it is working great for me. I 
> used Intellij Idea with the Asciidoc Plugin.
>
> Differently from Olivier's observation, the main developer-manual ist 
> updated when I make a change in developer-manual.adoc. Both html and 
> pdf include the change.
>
> It is not updated when I only change an included document like 
> accounting.adoc. I think it would be good to recreate all files if 
> they have chnaged or not. If I'm not wrong, both SVN and Git notice if 
> a file has not be changed even if it is rewritten so it should be no 
> problem.
>
> I think this is a good starting point, more pints might come up if we 
> use it more intensely.
>
> Thanks,
>
> Michael
>
>
> Am 21.02.18 um 14:08 schrieb Olivier Heintz:
>> Thank you for the work, Taher
>>
>> I have played with it and merge with my tests.
>> Currently, I have start from Accounting_Agreement, convert from 
>> docbook and update and
>> test renderer by both your gradle task and by AsciidocFx html button
>>
>> With a lot of include, result html file would be very large and in 
>> some case it will be good to be able to put a link in place
>> of include. Currenlty the generateOfbizDocumentation task doesn't 
>> generate file for doc in component even if the adoc file is
>> not in the _include directory.
>>
>> Just for information: With AsciidocFx (I have understood it use 
>> asciidoctor for generate html file, but I'm not sure)
>> it's not necessary to say include file is in _include directory, it 
>> read both in the current directory and in the _include one.
>> The generateOfbizDocumentation task doesn't use the same rule, we 
>> should say explicitly it's in the _include directory.
>>
>> The main "malfunction" of the generateOfbizDocumentation task is that 
>> it not re-generate the html file if it already exist
>> even if the main adoc file was modified. So it's needed to remove it 
>> manually before call generateOfbizDocumentation.
>>
>> Thank you for your usage of leveloffset, it's generated by docbook 
>> conversion, but now I understand how it works ;-)
>>
>>
>> Olivier
>>
>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit :
>>> Hello documentation team and everyone
>>>
>>> I have created a slightly modified design of the documentation
>>> framework with some sample contents in [1]. I highlight the changes
>>> below:
>>> - Created a new top-level directory called "docs/asciidoc". The reason
>>> is so that we have more than one possible manual.
>>> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
>>> - Created "Apache OFBiz Developer Manual" in 
>>> docs/asciidoc/developer-manual.adoc
>>> - Created a sample document in the accounting component to show how
>>> documents are linked together.
>>> - Used a special directive called "leveloffset" in the include
>>> directive. This directive shifts the headers of the included document
>>> (H2 becomes H3, and so on) so that sub-sections can be published
>>> separately.
>>> - Created a task called generateOfbizDocumentation to generate the
>>> documentation (both PDF and HTML) for framework + core apps
>>> - Created a task called generatePluginDocumentation
>>> -PpluginId=whatever to generate the documentation for a single plugin.
>>>
>>> That's it. It's simple, easy to understand and I think you might like
>>> it. Any feedback is welcome, and I'll talk to you soon over Skype.
>>>
>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>
>>> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
>>>> Hi Taher
>>>>
>>>> I think a documentation team would be a great idea. There are 
>>>> people that have indicated that they'd like to help out with 
>>>> documentation tasks on the user list so that is where I'd recruit 
>>>> some people from. As long as people know what they need to do to 
>>>> create the patches then it will become a funnel process of getting 
>>>> it committed.
>>>>
>>>> We need a plan to consolidate the information sitting in the wiki 
>>>> and getting it put into the documentation framework (and this work 
>>>> will then significantly clear up the wiki!).
>>>>
>>>> My availability is pretty bad this week so hope to pick this up 
>>>> again or start the recruitment campaign next week :-)
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018/01/28 10:12:41, Taher Alkhateeb 
>>>> <sl...@gmail.com> wrote:
>>>>> Like Michael I think it is also a minor point. The reason I chose 
>>>>> this
>>>>> structure is because it is the default one for asciidoctor and is 
>>>>> flexible
>>>>> for the future, so Paul also makes a good point. Any structure is 
>>>>> fine by
>>>>> me, the real important work is getting the documentation right 
>>>>> which is
>>>>> very exciting to me.
>>>>>
>>>>> I will create a patch soon for a base level structure and publishing
>>>>> options for both HTML and PDF. It would be fantastic if we can 
>>>>> unify _all_
>>>>> of our documentation here including stuff currently in the wiki. 
>>>>> This way
>>>>> any changes to code are reflected (probably in the same commit) 
>>>>> with the
>>>>> relevant documentation.
>>>>>
>>>>> I think we should start to consider maybe forming a team willing 
>>>>> to help.
>>>>> This is a big, but extremely important thing to have. If we do 
>>>>> this right
>>>>> then I think adoption rates would increase and our community would 
>>>>> get
>>>>> larger.
>>>>>
>>>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" 
>>>>> <mi...@ecomify.de> wrote:
>>>>>
>>>>> Hi Paul,
>>>>>
>>>>> this is only a minor point for me, it just saves one 
>>>>> folder/structure level.
>>>>>
>>>>> If we want to stay open for other documentation frameworks in the 
>>>>> future,
>>>>> it might be better to keep the proposed structure.
>>>>>
>>>>> Best regards,
>>>>>
>>>>> Michael
>>>>>
>>>>>
>>>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>>>>>
>>>>> On 26 January 2018 at 19:53, Michael Brohl 
>>>>> <mi...@ecomify.de> wrote:
>>>>>>
>>>>>> with a small modification: I don't think we'll need a two-folder 
>>>>>> structure
>>>>>>> /docs/asciidoc, only /docs should be sufficient, no?
>>>>>>>
>>>>>>> Hi Michael,
>>>>>> We have streamlined the build system in other places by having 
>>>>>> folders for
>>>>>> the source language: groovyScripts, minilang, src/main/java .
>>>>>>
>>>>>> It means Groovy and other build tools can have default rules for 
>>>>>> what to do
>>>>>> with the contents of a language folder, and allows for the 
>>>>>> possibility of
>>>>>> other languages in future if necessary.
>>>>>>
>>>>>> The extra layer is only a minor nuisance. I think I'd prefer to 
>>>>>> keep it.
>>>>>> What do you see as the disadvantages?
>>>>>>
>>>>>> Cheers
>>>>>>
>>>>>> Paul Foxworthy
>>>>>>
>>>>>>
>
>

Re: [Discussion] documentation framework for OFBiz

[Michael Brohl <mi...@ecomify.de>]

No problem Taher, please take your time.

It was just a thought while playing with your PoC, it's not urgent.


Am 24.02.18 um 16:30 schrieb Taher Alkhateeb:
> One of the design goals I had in mind is to make things publishable
> from the component as well as from the master manual. To do that, I
> need to think of a proper way for handling all kinds of artifacts like
> images, and sub-content. So I can't answer you immediately without
> some review first. I'll provide a patch as soon as I've figured it
> out. It's a bit tricky because the images directory shifts and is
> handled differently based on your location in the directory structure.
>
> On Sat, Feb 24, 2018 at 6:15 PM, Michael Brohl <mi...@ecomify.de> wrote:
>> Hi Taher,
>>
>> maybe it's enough to only define a convention, like an include directory
>> below each documentation folder?
>>
>> src / docs / asciidoc / includes
>>
>> ord maybe
>>
>> src / docs / includes
>>
>> if they should be reusable also with other documentation frameworks?
>>
>>
>> Am 24.02.18 um 16:12 schrieb Taher Alkhateeb:
>>
>>> I haven't yet setup the images variables yet, but it is relatively
>>> trivial. For now you can simply include using a relative directory
>>> format. I will update the PoC to include images
>>>
>>> On Sat, Feb 24, 2018 at 6:10 PM, Michael Brohl <mi...@ecomify.de>
>>> wrote:
>>>> I have a question regarding included media files (images etc.) for
>>>> documentation. Where are they supposed to be stored?
>>>>
>>>> Regards,
>>>>
>>>> Michael Brohl
>>>> ecomify GmbH
>>>> www.ecomify.de
>>>>
>>>>
>>>> Am 24.02.18 um 15:44 schrieb Michael Brohl:
>>>>
>>>>> I have tried Taher's latest patch and it is working great for me. I used
>>>>> Intellij Idea with the Asciidoc Plugin.
>>>>>
>>>>> Differently from Olivier's observation, the main developer-manual ist
>>>>> updated when I make a change in developer-manual.adoc. Both html and pdf
>>>>> include the change.
>>>>>
>>>>> It is not updated when I only change an included document like
>>>>> accounting.adoc. I think it would be good to recreate all files if they
>>>>> have
>>>>> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has
>>>>> not
>>>>> be changed even if it is rewritten so it should be no problem.
>>>>>
>>>>> I think this is a good starting point, more pints might come up if we
>>>>> use
>>>>> it more intensely.
>>>>>
>>>>> Thanks,
>>>>>
>>>>> Michael
>>>>>
>>>>>
>>>>> Am 21.02.18 um 14:08 schrieb Olivier Heintz:
>>>>>> Thank you for the work, Taher
>>>>>>
>>>>>> I have played with it and merge with my tests.
>>>>>> Currently, I have start from Accounting_Agreement, convert from docbook
>>>>>> and update and
>>>>>> test renderer by both your gradle task and by AsciidocFx html button
>>>>>>
>>>>>> With a lot of include, result html file would be very large and in some
>>>>>> case it will be good to be able to put a link in place
>>>>>> of include. Currenlty the generateOfbizDocumentation task doesn't
>>>>>> generate file for doc in component even if the adoc file is
>>>>>> not in the _include directory.
>>>>>>
>>>>>> Just for information: With AsciidocFx (I have understood it use
>>>>>> asciidoctor for generate html file, but I'm not sure)
>>>>>> it's not necessary to say include file is in _include directory, it
>>>>>> read
>>>>>> both in the current directory and in the _include one.
>>>>>> The generateOfbizDocumentation task doesn't use the same rule, we
>>>>>> should
>>>>>> say explicitly it's in the _include directory.
>>>>>>
>>>>>> The main "malfunction" of the generateOfbizDocumentation task is that
>>>>>> it
>>>>>> not re-generate the html file if it already exist
>>>>>> even if the main adoc file was modified. So it's needed to remove it
>>>>>> manually before call generateOfbizDocumentation.
>>>>>>
>>>>>> Thank you for your usage of leveloffset, it's generated by docbook
>>>>>> conversion, but now I understand how it works ;-)
>>>>>>
>>>>>>
>>>>>> Olivier
>>>>>>
>>>>>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit :
>>>>>>> Hello documentation team and everyone
>>>>>>>
>>>>>>> I have created a slightly modified design of the documentation
>>>>>>> framework with some sample contents in [1]. I highlight the changes
>>>>>>> below:
>>>>>>> - Created a new top-level directory called "docs/asciidoc". The reason
>>>>>>> is so that we have more than one possible manual.
>>>>>>> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
>>>>>>> - Created "Apache OFBiz Developer Manual" in
>>>>>>> docs/asciidoc/developer-manual.adoc
>>>>>>> - Created a sample document in the accounting component to show how
>>>>>>> documents are linked together.
>>>>>>> - Used a special directive called "leveloffset" in the include
>>>>>>> directive. This directive shifts the headers of the included document
>>>>>>> (H2 becomes H3, and so on) so that sub-sections can be published
>>>>>>> separately.
>>>>>>> - Created a task called generateOfbizDocumentation to generate the
>>>>>>> documentation (both PDF and HTML) for framework + core apps
>>>>>>> - Created a task called generatePluginDocumentation
>>>>>>> -PpluginId=whatever to generate the documentation for a single plugin.
>>>>>>>
>>>>>>> That's it. It's simple, easy to understand and I think you might like
>>>>>>> it. Any feedback is welcome, and I'll talk to you soon over Skype.
>>>>>>>
>>>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>>>
>>>>>>> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org>
>>>>>>> wrote:
>>>>>>>> Hi Taher
>>>>>>>>
>>>>>>>> I think a documentation team would be a great idea. There are people
>>>>>>>> that have indicated that they'd like to help out with documentation
>>>>>>>> tasks on
>>>>>>>> the user list so that is where I'd recruit some people from. As long
>>>>>>>> as
>>>>>>>> people know what they need to do to create the patches then it will
>>>>>>>> become a
>>>>>>>> funnel process of getting it committed.
>>>>>>>>
>>>>>>>> We need a plan to consolidate the information sitting in the wiki and
>>>>>>>> getting it put into the documentation framework (and this work will
>>>>>>>> then
>>>>>>>> significantly clear up the wiki!).
>>>>>>>>
>>>>>>>> My availability is pretty bad this week so hope to pick this up again
>>>>>>>> or start the recruitment campaign next week :-)
>>>>>>>>
>>>>>>>> Thanks
>>>>>>>> Sharan
>>>>>>>>
>>>>>>>> On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com>
>>>>>>>> wrote:
>>>>>>>>> Like Michael I think it is also a minor point. The reason I chose
>>>>>>>>> this
>>>>>>>>> structure is because it is the default one for asciidoctor and is
>>>>>>>>> flexible
>>>>>>>>> for the future, so Paul also makes a good point. Any structure is
>>>>>>>>> fine
>>>>>>>>> by
>>>>>>>>> me, the real important work is getting the documentation right which
>>>>>>>>> is
>>>>>>>>> very exciting to me.
>>>>>>>>>
>>>>>>>>> I will create a patch soon for a base level structure and publishing
>>>>>>>>> options for both HTML and PDF. It would be fantastic if we can unify
>>>>>>>>> _all_
>>>>>>>>> of our documentation here including stuff currently in the wiki.
>>>>>>>>> This
>>>>>>>>> way
>>>>>>>>> any changes to code are reflected (probably in the same commit) with
>>>>>>>>> the
>>>>>>>>> relevant documentation.
>>>>>>>>>
>>>>>>>>> I think we should start to consider maybe forming a team willing to
>>>>>>>>> help.
>>>>>>>>> This is a big, but extremely important thing to have. If we do this
>>>>>>>>> right
>>>>>>>>> then I think adoption rates would increase and our community would
>>>>>>>>> get
>>>>>>>>> larger.
>>>>>>>>>
>>>>>>>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de>
>>>>>>>>> wrote:
>>>>>>>>>
>>>>>>>>> Hi Paul,
>>>>>>>>>
>>>>>>>>> this is only a minor point for me, it just saves one
>>>>>>>>> folder/structure
>>>>>>>>> level.
>>>>>>>>>
>>>>>>>>> If we want to stay open for other documentation frameworks in the
>>>>>>>>> future,
>>>>>>>>> it might be better to keep the proposed structure.
>>>>>>>>>
>>>>>>>>> Best regards,
>>>>>>>>>
>>>>>>>>> Michael
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>>>>>>>>>
>>>>>>>>> On 26 January 2018 at 19:53, Michael Brohl
>>>>>>>>> <mi...@ecomify.de>
>>>>>>>>> wrote:
>>>>>>>>>>
>>>>>>>>>> with a small modification: I don't think we'll need a two-folder
>>>>>>>>>> structure
>>>>>>>>>>> /docs/asciidoc, only /docs should be sufficient, no?
>>>>>>>>>>>
>>>>>>>>>>> Hi Michael,
>>>>>>>>>> We have streamlined the build system in other places by having
>>>>>>>>>> folders for
>>>>>>>>>> the source language: groovyScripts, minilang, src/main/java .
>>>>>>>>>>
>>>>>>>>>> It means Groovy and other build tools can have default rules for
>>>>>>>>>> what
>>>>>>>>>> to do
>>>>>>>>>> with the contents of a language folder, and allows for the
>>>>>>>>>> possibility of
>>>>>>>>>> other languages in future if necessary.
>>>>>>>>>>
>>>>>>>>>> The extra layer is only a minor nuisance. I think I'd prefer to
>>>>>>>>>> keep
>>>>>>>>>> it.
>>>>>>>>>> What do you see as the disadvantages?
>>>>>>>>>>
>>>>>>>>>> Cheers
>>>>>>>>>>
>>>>>>>>>> Paul Foxworthy
>>>>>>>>>>
>>>>>>>>>>
>>

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

One of the design goals I had in mind is to make things publishable
from the component as well as from the master manual. To do that, I
need to think of a proper way for handling all kinds of artifacts like
images, and sub-content. So I can't answer you immediately without
some review first. I'll provide a patch as soon as I've figured it
out. It's a bit tricky because the images directory shifts and is
handled differently based on your location in the directory structure.

On Sat, Feb 24, 2018 at 6:15 PM, Michael Brohl <mi...@ecomify.de> wrote:
> Hi Taher,
>
> maybe it's enough to only define a convention, like an include directory
> below each documentation folder?
>
> src / docs / asciidoc / includes
>
> ord maybe
>
> src / docs / includes
>
> if they should be reusable also with other documentation frameworks?
>
>
> Am 24.02.18 um 16:12 schrieb Taher Alkhateeb:
>
>> I haven't yet setup the images variables yet, but it is relatively
>> trivial. For now you can simply include using a relative directory
>> format. I will update the PoC to include images
>>
>> On Sat, Feb 24, 2018 at 6:10 PM, Michael Brohl <mi...@ecomify.de>
>> wrote:
>>>
>>> I have a question regarding included media files (images etc.) for
>>> documentation. Where are they supposed to be stored?
>>>
>>> Regards,
>>>
>>> Michael Brohl
>>> ecomify GmbH
>>> www.ecomify.de
>>>
>>>
>>> Am 24.02.18 um 15:44 schrieb Michael Brohl:
>>>
>>>> I have tried Taher's latest patch and it is working great for me. I used
>>>> Intellij Idea with the Asciidoc Plugin.
>>>>
>>>> Differently from Olivier's observation, the main developer-manual ist
>>>> updated when I make a change in developer-manual.adoc. Both html and pdf
>>>> include the change.
>>>>
>>>> It is not updated when I only change an included document like
>>>> accounting.adoc. I think it would be good to recreate all files if they
>>>> have
>>>> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has
>>>> not
>>>> be changed even if it is rewritten so it should be no problem.
>>>>
>>>> I think this is a good starting point, more pints might come up if we
>>>> use
>>>> it more intensely.
>>>>
>>>> Thanks,
>>>>
>>>> Michael
>>>>
>>>>
>>>> Am 21.02.18 um 14:08 schrieb Olivier Heintz:
>>>>>
>>>>> Thank you for the work, Taher
>>>>>
>>>>> I have played with it and merge with my tests.
>>>>> Currently, I have start from Accounting_Agreement, convert from docbook
>>>>> and update and
>>>>> test renderer by both your gradle task and by AsciidocFx html button
>>>>>
>>>>> With a lot of include, result html file would be very large and in some
>>>>> case it will be good to be able to put a link in place
>>>>> of include. Currenlty the generateOfbizDocumentation task doesn't
>>>>> generate file for doc in component even if the adoc file is
>>>>> not in the _include directory.
>>>>>
>>>>> Just for information: With AsciidocFx (I have understood it use
>>>>> asciidoctor for generate html file, but I'm not sure)
>>>>> it's not necessary to say include file is in _include directory, it
>>>>> read
>>>>> both in the current directory and in the _include one.
>>>>> The generateOfbizDocumentation task doesn't use the same rule, we
>>>>> should
>>>>> say explicitly it's in the _include directory.
>>>>>
>>>>> The main "malfunction" of the generateOfbizDocumentation task is that
>>>>> it
>>>>> not re-generate the html file if it already exist
>>>>> even if the main adoc file was modified. So it's needed to remove it
>>>>> manually before call generateOfbizDocumentation.
>>>>>
>>>>> Thank you for your usage of leveloffset, it's generated by docbook
>>>>> conversion, but now I understand how it works ;-)
>>>>>
>>>>>
>>>>> Olivier
>>>>>
>>>>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit :
>>>>>>
>>>>>> Hello documentation team and everyone
>>>>>>
>>>>>> I have created a slightly modified design of the documentation
>>>>>> framework with some sample contents in [1]. I highlight the changes
>>>>>> below:
>>>>>> - Created a new top-level directory called "docs/asciidoc". The reason
>>>>>> is so that we have more than one possible manual.
>>>>>> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
>>>>>> - Created "Apache OFBiz Developer Manual" in
>>>>>> docs/asciidoc/developer-manual.adoc
>>>>>> - Created a sample document in the accounting component to show how
>>>>>> documents are linked together.
>>>>>> - Used a special directive called "leveloffset" in the include
>>>>>> directive. This directive shifts the headers of the included document
>>>>>> (H2 becomes H3, and so on) so that sub-sections can be published
>>>>>> separately.
>>>>>> - Created a task called generateOfbizDocumentation to generate the
>>>>>> documentation (both PDF and HTML) for framework + core apps
>>>>>> - Created a task called generatePluginDocumentation
>>>>>> -PpluginId=whatever to generate the documentation for a single plugin.
>>>>>>
>>>>>> That's it. It's simple, easy to understand and I think you might like
>>>>>> it. Any feedback is welcome, and I'll talk to you soon over Skype.
>>>>>>
>>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>>
>>>>>> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org>
>>>>>> wrote:
>>>>>>>
>>>>>>> Hi Taher
>>>>>>>
>>>>>>> I think a documentation team would be a great idea. There are people
>>>>>>> that have indicated that they'd like to help out with documentation
>>>>>>> tasks on
>>>>>>> the user list so that is where I'd recruit some people from. As long
>>>>>>> as
>>>>>>> people know what they need to do to create the patches then it will
>>>>>>> become a
>>>>>>> funnel process of getting it committed.
>>>>>>>
>>>>>>> We need a plan to consolidate the information sitting in the wiki and
>>>>>>> getting it put into the documentation framework (and this work will
>>>>>>> then
>>>>>>> significantly clear up the wiki!).
>>>>>>>
>>>>>>> My availability is pretty bad this week so hope to pick this up again
>>>>>>> or start the recruitment campaign next week :-)
>>>>>>>
>>>>>>> Thanks
>>>>>>> Sharan
>>>>>>>
>>>>>>> On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com>
>>>>>>> wrote:
>>>>>>>>
>>>>>>>> Like Michael I think it is also a minor point. The reason I chose
>>>>>>>> this
>>>>>>>> structure is because it is the default one for asciidoctor and is
>>>>>>>> flexible
>>>>>>>> for the future, so Paul also makes a good point. Any structure is
>>>>>>>> fine
>>>>>>>> by
>>>>>>>> me, the real important work is getting the documentation right which
>>>>>>>> is
>>>>>>>> very exciting to me.
>>>>>>>>
>>>>>>>> I will create a patch soon for a base level structure and publishing
>>>>>>>> options for both HTML and PDF. It would be fantastic if we can unify
>>>>>>>> _all_
>>>>>>>> of our documentation here including stuff currently in the wiki.
>>>>>>>> This
>>>>>>>> way
>>>>>>>> any changes to code are reflected (probably in the same commit) with
>>>>>>>> the
>>>>>>>> relevant documentation.
>>>>>>>>
>>>>>>>> I think we should start to consider maybe forming a team willing to
>>>>>>>> help.
>>>>>>>> This is a big, but extremely important thing to have. If we do this
>>>>>>>> right
>>>>>>>> then I think adoption rates would increase and our community would
>>>>>>>> get
>>>>>>>> larger.
>>>>>>>>
>>>>>>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de>
>>>>>>>> wrote:
>>>>>>>>
>>>>>>>> Hi Paul,
>>>>>>>>
>>>>>>>> this is only a minor point for me, it just saves one
>>>>>>>> folder/structure
>>>>>>>> level.
>>>>>>>>
>>>>>>>> If we want to stay open for other documentation frameworks in the
>>>>>>>> future,
>>>>>>>> it might be better to keep the proposed structure.
>>>>>>>>
>>>>>>>> Best regards,
>>>>>>>>
>>>>>>>> Michael
>>>>>>>>
>>>>>>>>
>>>>>>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>>>>>>>>
>>>>>>>> On 26 January 2018 at 19:53, Michael Brohl
>>>>>>>> <mi...@ecomify.de>
>>>>>>>> wrote:
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> with a small modification: I don't think we'll need a two-folder
>>>>>>>>> structure
>>>>>>>>>>
>>>>>>>>>> /docs/asciidoc, only /docs should be sufficient, no?
>>>>>>>>>>
>>>>>>>>>> Hi Michael,
>>>>>>>>>
>>>>>>>>> We have streamlined the build system in other places by having
>>>>>>>>> folders for
>>>>>>>>> the source language: groovyScripts, minilang, src/main/java .
>>>>>>>>>
>>>>>>>>> It means Groovy and other build tools can have default rules for
>>>>>>>>> what
>>>>>>>>> to do
>>>>>>>>> with the contents of a language folder, and allows for the
>>>>>>>>> possibility of
>>>>>>>>> other languages in future if necessary.
>>>>>>>>>
>>>>>>>>> The extra layer is only a minor nuisance. I think I'd prefer to
>>>>>>>>> keep
>>>>>>>>> it.
>>>>>>>>> What do you see as the disadvantages?
>>>>>>>>>
>>>>>>>>> Cheers
>>>>>>>>>
>>>>>>>>> Paul Foxworthy
>>>>>>>>>
>>>>>>>>>
>>>>
>>>
>
>

Re: [Discussion] documentation framework for OFBiz

[Michael Brohl <mi...@ecomify.de>]

Hi Taher,

maybe it's enough to only define a convention, like an include directory 
below each documentation folder?

src / docs / asciidoc / includes

ord maybe

src / docs / includes

if they should be reusable also with other documentation frameworks?


Am 24.02.18 um 16:12 schrieb Taher Alkhateeb:
> I haven't yet setup the images variables yet, but it is relatively
> trivial. For now you can simply include using a relative directory
> format. I will update the PoC to include images
>
> On Sat, Feb 24, 2018 at 6:10 PM, Michael Brohl <mi...@ecomify.de> wrote:
>> I have a question regarding included media files (images etc.) for
>> documentation. Where are they supposed to be stored?
>>
>> Regards,
>>
>> Michael Brohl
>> ecomify GmbH
>> www.ecomify.de
>>
>>
>> Am 24.02.18 um 15:44 schrieb Michael Brohl:
>>
>>> I have tried Taher's latest patch and it is working great for me. I used
>>> Intellij Idea with the Asciidoc Plugin.
>>>
>>> Differently from Olivier's observation, the main developer-manual ist
>>> updated when I make a change in developer-manual.adoc. Both html and pdf
>>> include the change.
>>>
>>> It is not updated when I only change an included document like
>>> accounting.adoc. I think it would be good to recreate all files if they have
>>> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not
>>> be changed even if it is rewritten so it should be no problem.
>>>
>>> I think this is a good starting point, more pints might come up if we use
>>> it more intensely.
>>>
>>> Thanks,
>>>
>>> Michael
>>>
>>>
>>> Am 21.02.18 um 14:08 schrieb Olivier Heintz:
>>>> Thank you for the work, Taher
>>>>
>>>> I have played with it and merge with my tests.
>>>> Currently, I have start from Accounting_Agreement, convert from docbook
>>>> and update and
>>>> test renderer by both your gradle task and by AsciidocFx html button
>>>>
>>>> With a lot of include, result html file would be very large and in some
>>>> case it will be good to be able to put a link in place
>>>> of include. Currenlty the generateOfbizDocumentation task doesn't
>>>> generate file for doc in component even if the adoc file is
>>>> not in the _include directory.
>>>>
>>>> Just for information: With AsciidocFx (I have understood it use
>>>> asciidoctor for generate html file, but I'm not sure)
>>>> it's not necessary to say include file is in _include directory, it read
>>>> both in the current directory and in the _include one.
>>>> The generateOfbizDocumentation task doesn't use the same rule, we should
>>>> say explicitly it's in the _include directory.
>>>>
>>>> The main "malfunction" of the generateOfbizDocumentation task is that it
>>>> not re-generate the html file if it already exist
>>>> even if the main adoc file was modified. So it's needed to remove it
>>>> manually before call generateOfbizDocumentation.
>>>>
>>>> Thank you for your usage of leveloffset, it's generated by docbook
>>>> conversion, but now I understand how it works ;-)
>>>>
>>>>
>>>> Olivier
>>>>
>>>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit :
>>>>> Hello documentation team and everyone
>>>>>
>>>>> I have created a slightly modified design of the documentation
>>>>> framework with some sample contents in [1]. I highlight the changes
>>>>> below:
>>>>> - Created a new top-level directory called "docs/asciidoc". The reason
>>>>> is so that we have more than one possible manual.
>>>>> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
>>>>> - Created "Apache OFBiz Developer Manual" in
>>>>> docs/asciidoc/developer-manual.adoc
>>>>> - Created a sample document in the accounting component to show how
>>>>> documents are linked together.
>>>>> - Used a special directive called "leveloffset" in the include
>>>>> directive. This directive shifts the headers of the included document
>>>>> (H2 becomes H3, and so on) so that sub-sections can be published
>>>>> separately.
>>>>> - Created a task called generateOfbizDocumentation to generate the
>>>>> documentation (both PDF and HTML) for framework + core apps
>>>>> - Created a task called generatePluginDocumentation
>>>>> -PpluginId=whatever to generate the documentation for a single plugin.
>>>>>
>>>>> That's it. It's simple, easy to understand and I think you might like
>>>>> it. Any feedback is welcome, and I'll talk to you soon over Skype.
>>>>>
>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>
>>>>> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
>>>>>> Hi Taher
>>>>>>
>>>>>> I think a documentation team would be a great idea. There are people
>>>>>> that have indicated that they'd like to help out with documentation tasks on
>>>>>> the user list so that is where I'd recruit some people from. As long as
>>>>>> people know what they need to do to create the patches then it will become a
>>>>>> funnel process of getting it committed.
>>>>>>
>>>>>> We need a plan to consolidate the information sitting in the wiki and
>>>>>> getting it put into the documentation framework (and this work will then
>>>>>> significantly clear up the wiki!).
>>>>>>
>>>>>> My availability is pretty bad this week so hope to pick this up again
>>>>>> or start the recruitment campaign next week :-)
>>>>>>
>>>>>> Thanks
>>>>>> Sharan
>>>>>>
>>>>>> On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com>
>>>>>> wrote:
>>>>>>> Like Michael I think it is also a minor point. The reason I chose this
>>>>>>> structure is because it is the default one for asciidoctor and is
>>>>>>> flexible
>>>>>>> for the future, so Paul also makes a good point. Any structure is fine
>>>>>>> by
>>>>>>> me, the real important work is getting the documentation right which
>>>>>>> is
>>>>>>> very exciting to me.
>>>>>>>
>>>>>>> I will create a patch soon for a base level structure and publishing
>>>>>>> options for both HTML and PDF. It would be fantastic if we can unify
>>>>>>> _all_
>>>>>>> of our documentation here including stuff currently in the wiki. This
>>>>>>> way
>>>>>>> any changes to code are reflected (probably in the same commit) with
>>>>>>> the
>>>>>>> relevant documentation.
>>>>>>>
>>>>>>> I think we should start to consider maybe forming a team willing to
>>>>>>> help.
>>>>>>> This is a big, but extremely important thing to have. If we do this
>>>>>>> right
>>>>>>> then I think adoption rates would increase and our community would get
>>>>>>> larger.
>>>>>>>
>>>>>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de>
>>>>>>> wrote:
>>>>>>>
>>>>>>> Hi Paul,
>>>>>>>
>>>>>>> this is only a minor point for me, it just saves one folder/structure
>>>>>>> level.
>>>>>>>
>>>>>>> If we want to stay open for other documentation frameworks in the
>>>>>>> future,
>>>>>>> it might be better to keep the proposed structure.
>>>>>>>
>>>>>>> Best regards,
>>>>>>>
>>>>>>> Michael
>>>>>>>
>>>>>>>
>>>>>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>>>>>>>
>>>>>>> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de>
>>>>>>> wrote:
>>>>>>>>
>>>>>>>> with a small modification: I don't think we'll need a two-folder
>>>>>>>> structure
>>>>>>>>> /docs/asciidoc, only /docs should be sufficient, no?
>>>>>>>>>
>>>>>>>>> Hi Michael,
>>>>>>>> We have streamlined the build system in other places by having
>>>>>>>> folders for
>>>>>>>> the source language: groovyScripts, minilang, src/main/java .
>>>>>>>>
>>>>>>>> It means Groovy and other build tools can have default rules for what
>>>>>>>> to do
>>>>>>>> with the contents of a language folder, and allows for the
>>>>>>>> possibility of
>>>>>>>> other languages in future if necessary.
>>>>>>>>
>>>>>>>> The extra layer is only a minor nuisance. I think I'd prefer to keep
>>>>>>>> it.
>>>>>>>> What do you see as the disadvantages?
>>>>>>>>
>>>>>>>> Cheers
>>>>>>>>
>>>>>>>> Paul Foxworthy
>>>>>>>>
>>>>>>>>
>>>
>>

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

I haven't yet setup the images variables yet, but it is relatively
trivial. For now you can simply include using a relative directory
format. I will update the PoC to include images

On Sat, Feb 24, 2018 at 6:10 PM, Michael Brohl <mi...@ecomify.de> wrote:
> I have a question regarding included media files (images etc.) for
> documentation. Where are they supposed to be stored?
>
> Regards,
>
> Michael Brohl
> ecomify GmbH
> www.ecomify.de
>
>
> Am 24.02.18 um 15:44 schrieb Michael Brohl:
>
>> I have tried Taher's latest patch and it is working great for me. I used
>> Intellij Idea with the Asciidoc Plugin.
>>
>> Differently from Olivier's observation, the main developer-manual ist
>> updated when I make a change in developer-manual.adoc. Both html and pdf
>> include the change.
>>
>> It is not updated when I only change an included document like
>> accounting.adoc. I think it would be good to recreate all files if they have
>> chnaged or not. If I'm not wrong, both SVN and Git notice if a file has not
>> be changed even if it is rewritten so it should be no problem.
>>
>> I think this is a good starting point, more pints might come up if we use
>> it more intensely.
>>
>> Thanks,
>>
>> Michael
>>
>>
>> Am 21.02.18 um 14:08 schrieb Olivier Heintz:
>>>
>>> Thank you for the work, Taher
>>>
>>> I have played with it and merge with my tests.
>>> Currently, I have start from Accounting_Agreement, convert from docbook
>>> and update and
>>> test renderer by both your gradle task and by AsciidocFx html button
>>>
>>> With a lot of include, result html file would be very large and in some
>>> case it will be good to be able to put a link in place
>>> of include. Currenlty the generateOfbizDocumentation task doesn't
>>> generate file for doc in component even if the adoc file is
>>> not in the _include directory.
>>>
>>> Just for information: With AsciidocFx (I have understood it use
>>> asciidoctor for generate html file, but I'm not sure)
>>> it's not necessary to say include file is in _include directory, it read
>>> both in the current directory and in the _include one.
>>> The generateOfbizDocumentation task doesn't use the same rule, we should
>>> say explicitly it's in the _include directory.
>>>
>>> The main "malfunction" of the generateOfbizDocumentation task is that it
>>> not re-generate the html file if it already exist
>>> even if the main adoc file was modified. So it's needed to remove it
>>> manually before call generateOfbizDocumentation.
>>>
>>> Thank you for your usage of leveloffset, it's generated by docbook
>>> conversion, but now I understand how it works ;-)
>>>
>>>
>>> Olivier
>>>
>>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit :
>>>>
>>>> Hello documentation team and everyone
>>>>
>>>> I have created a slightly modified design of the documentation
>>>> framework with some sample contents in [1]. I highlight the changes
>>>> below:
>>>> - Created a new top-level directory called "docs/asciidoc". The reason
>>>> is so that we have more than one possible manual.
>>>> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
>>>> - Created "Apache OFBiz Developer Manual" in
>>>> docs/asciidoc/developer-manual.adoc
>>>> - Created a sample document in the accounting component to show how
>>>> documents are linked together.
>>>> - Used a special directive called "leveloffset" in the include
>>>> directive. This directive shifts the headers of the included document
>>>> (H2 becomes H3, and so on) so that sub-sections can be published
>>>> separately.
>>>> - Created a task called generateOfbizDocumentation to generate the
>>>> documentation (both PDF and HTML) for framework + core apps
>>>> - Created a task called generatePluginDocumentation
>>>> -PpluginId=whatever to generate the documentation for a single plugin.
>>>>
>>>> That's it. It's simple, easy to understand and I think you might like
>>>> it. Any feedback is welcome, and I'll talk to you soon over Skype.
>>>>
>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>
>>>> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
>>>>>
>>>>> Hi Taher
>>>>>
>>>>> I think a documentation team would be a great idea. There are people
>>>>> that have indicated that they'd like to help out with documentation tasks on
>>>>> the user list so that is where I'd recruit some people from. As long as
>>>>> people know what they need to do to create the patches then it will become a
>>>>> funnel process of getting it committed.
>>>>>
>>>>> We need a plan to consolidate the information sitting in the wiki and
>>>>> getting it put into the documentation framework (and this work will then
>>>>> significantly clear up the wiki!).
>>>>>
>>>>> My availability is pretty bad this week so hope to pick this up again
>>>>> or start the recruitment campaign next week :-)
>>>>>
>>>>> Thanks
>>>>> Sharan
>>>>>
>>>>> On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com>
>>>>> wrote:
>>>>>>
>>>>>> Like Michael I think it is also a minor point. The reason I chose this
>>>>>> structure is because it is the default one for asciidoctor and is
>>>>>> flexible
>>>>>> for the future, so Paul also makes a good point. Any structure is fine
>>>>>> by
>>>>>> me, the real important work is getting the documentation right which
>>>>>> is
>>>>>> very exciting to me.
>>>>>>
>>>>>> I will create a patch soon for a base level structure and publishing
>>>>>> options for both HTML and PDF. It would be fantastic if we can unify
>>>>>> _all_
>>>>>> of our documentation here including stuff currently in the wiki. This
>>>>>> way
>>>>>> any changes to code are reflected (probably in the same commit) with
>>>>>> the
>>>>>> relevant documentation.
>>>>>>
>>>>>> I think we should start to consider maybe forming a team willing to
>>>>>> help.
>>>>>> This is a big, but extremely important thing to have. If we do this
>>>>>> right
>>>>>> then I think adoption rates would increase and our community would get
>>>>>> larger.
>>>>>>
>>>>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de>
>>>>>> wrote:
>>>>>>
>>>>>> Hi Paul,
>>>>>>
>>>>>> this is only a minor point for me, it just saves one folder/structure
>>>>>> level.
>>>>>>
>>>>>> If we want to stay open for other documentation frameworks in the
>>>>>> future,
>>>>>> it might be better to keep the proposed structure.
>>>>>>
>>>>>> Best regards,
>>>>>>
>>>>>> Michael
>>>>>>
>>>>>>
>>>>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>>>>>>
>>>>>> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de>
>>>>>> wrote:
>>>>>>>
>>>>>>>
>>>>>>> with a small modification: I don't think we'll need a two-folder
>>>>>>> structure
>>>>>>>>
>>>>>>>> /docs/asciidoc, only /docs should be sufficient, no?
>>>>>>>>
>>>>>>>> Hi Michael,
>>>>>>>
>>>>>>> We have streamlined the build system in other places by having
>>>>>>> folders for
>>>>>>> the source language: groovyScripts, minilang, src/main/java .
>>>>>>>
>>>>>>> It means Groovy and other build tools can have default rules for what
>>>>>>> to do
>>>>>>> with the contents of a language folder, and allows for the
>>>>>>> possibility of
>>>>>>> other languages in future if necessary.
>>>>>>>
>>>>>>> The extra layer is only a minor nuisance. I think I'd prefer to keep
>>>>>>> it.
>>>>>>> What do you see as the disadvantages?
>>>>>>>
>>>>>>> Cheers
>>>>>>>
>>>>>>> Paul Foxworthy
>>>>>>>
>>>>>>>
>>
>>
>
>

Re: [Discussion] documentation framework for OFBiz

[Michael Brohl <mi...@ecomify.de>]

I have a question regarding included media files (images etc.) for 
documentation. Where are they supposed to be stored?

Regards,

Michael Brohl
ecomify GmbH
www.ecomify.de


Am 24.02.18 um 15:44 schrieb Michael Brohl:
> I have tried Taher's latest patch and it is working great for me. I 
> used Intellij Idea with the Asciidoc Plugin.
>
> Differently from Olivier's observation, the main developer-manual ist 
> updated when I make a change in developer-manual.adoc. Both html and 
> pdf include the change.
>
> It is not updated when I only change an included document like 
> accounting.adoc. I think it would be good to recreate all files if 
> they have chnaged or not. If I'm not wrong, both SVN and Git notice if 
> a file has not be changed even if it is rewritten so it should be no 
> problem.
>
> I think this is a good starting point, more pints might come up if we 
> use it more intensely.
>
> Thanks,
>
> Michael
>
>
> Am 21.02.18 um 14:08 schrieb Olivier Heintz:
>> Thank you for the work, Taher
>>
>> I have played with it and merge with my tests.
>> Currently, I have start from Accounting_Agreement, convert from 
>> docbook and update and
>> test renderer by both your gradle task and by AsciidocFx html button
>>
>> With a lot of include, result html file would be very large and in 
>> some case it will be good to be able to put a link in place
>> of include. Currenlty the generateOfbizDocumentation task doesn't 
>> generate file for doc in component even if the adoc file is
>> not in the _include directory.
>>
>> Just for information: With AsciidocFx (I have understood it use 
>> asciidoctor for generate html file, but I'm not sure)
>> it's not necessary to say include file is in _include directory, it 
>> read both in the current directory and in the _include one.
>> The generateOfbizDocumentation task doesn't use the same rule, we 
>> should say explicitly it's in the _include directory.
>>
>> The main "malfunction" of the generateOfbizDocumentation task is that 
>> it not re-generate the html file if it already exist
>> even if the main adoc file was modified. So it's needed to remove it 
>> manually before call generateOfbizDocumentation.
>>
>> Thank you for your usage of leveloffset, it's generated by docbook 
>> conversion, but now I understand how it works ;-)
>>
>>
>> Olivier
>>
>> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit :
>>> Hello documentation team and everyone
>>>
>>> I have created a slightly modified design of the documentation
>>> framework with some sample contents in [1]. I highlight the changes
>>> below:
>>> - Created a new top-level directory called "docs/asciidoc". The reason
>>> is so that we have more than one possible manual.
>>> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
>>> - Created "Apache OFBiz Developer Manual" in 
>>> docs/asciidoc/developer-manual.adoc
>>> - Created a sample document in the accounting component to show how
>>> documents are linked together.
>>> - Used a special directive called "leveloffset" in the include
>>> directive. This directive shifts the headers of the included document
>>> (H2 becomes H3, and so on) so that sub-sections can be published
>>> separately.
>>> - Created a task called generateOfbizDocumentation to generate the
>>> documentation (both PDF and HTML) for framework + core apps
>>> - Created a task called generatePluginDocumentation
>>> -PpluginId=whatever to generate the documentation for a single plugin.
>>>
>>> That's it. It's simple, easy to understand and I think you might like
>>> it. Any feedback is welcome, and I'll talk to you soon over Skype.
>>>
>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>
>>> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
>>>> Hi Taher
>>>>
>>>> I think a documentation team would be a great idea. There are 
>>>> people that have indicated that they'd like to help out with 
>>>> documentation tasks on the user list so that is where I'd recruit 
>>>> some people from. As long as people know what they need to do to 
>>>> create the patches then it will become a funnel process of getting 
>>>> it committed.
>>>>
>>>> We need a plan to consolidate the information sitting in the wiki 
>>>> and getting it put into the documentation framework (and this work 
>>>> will then significantly clear up the wiki!).
>>>>
>>>> My availability is pretty bad this week so hope to pick this up 
>>>> again or start the recruitment campaign next week :-)
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018/01/28 10:12:41, Taher Alkhateeb 
>>>> <sl...@gmail.com> wrote:
>>>>> Like Michael I think it is also a minor point. The reason I chose 
>>>>> this
>>>>> structure is because it is the default one for asciidoctor and is 
>>>>> flexible
>>>>> for the future, so Paul also makes a good point. Any structure is 
>>>>> fine by
>>>>> me, the real important work is getting the documentation right 
>>>>> which is
>>>>> very exciting to me.
>>>>>
>>>>> I will create a patch soon for a base level structure and publishing
>>>>> options for both HTML and PDF. It would be fantastic if we can 
>>>>> unify _all_
>>>>> of our documentation here including stuff currently in the wiki. 
>>>>> This way
>>>>> any changes to code are reflected (probably in the same commit) 
>>>>> with the
>>>>> relevant documentation.
>>>>>
>>>>> I think we should start to consider maybe forming a team willing 
>>>>> to help.
>>>>> This is a big, but extremely important thing to have. If we do 
>>>>> this right
>>>>> then I think adoption rates would increase and our community would 
>>>>> get
>>>>> larger.
>>>>>
>>>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" 
>>>>> <mi...@ecomify.de> wrote:
>>>>>
>>>>> Hi Paul,
>>>>>
>>>>> this is only a minor point for me, it just saves one 
>>>>> folder/structure level.
>>>>>
>>>>> If we want to stay open for other documentation frameworks in the 
>>>>> future,
>>>>> it might be better to keep the proposed structure.
>>>>>
>>>>> Best regards,
>>>>>
>>>>> Michael
>>>>>
>>>>>
>>>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>>>>>
>>>>> On 26 January 2018 at 19:53, Michael Brohl 
>>>>> <mi...@ecomify.de> wrote:
>>>>>>
>>>>>> with a small modification: I don't think we'll need a two-folder 
>>>>>> structure
>>>>>>> /docs/asciidoc, only /docs should be sufficient, no?
>>>>>>>
>>>>>>> Hi Michael,
>>>>>> We have streamlined the build system in other places by having 
>>>>>> folders for
>>>>>> the source language: groovyScripts, minilang, src/main/java .
>>>>>>
>>>>>> It means Groovy and other build tools can have default rules for 
>>>>>> what to do
>>>>>> with the contents of a language folder, and allows for the 
>>>>>> possibility of
>>>>>> other languages in future if necessary.
>>>>>>
>>>>>> The extra layer is only a minor nuisance. I think I'd prefer to 
>>>>>> keep it.
>>>>>> What do you see as the disadvantages?
>>>>>>
>>>>>> Cheers
>>>>>>
>>>>>> Paul Foxworthy
>>>>>>
>>>>>>
>
>

Re: [Discussion] documentation framework for OFBiz

[Michael Brohl <mi...@ecomify.de>]

I have tried Taher's latest patch and it is working great for me. I used 
Intellij Idea with the Asciidoc Plugin.

Differently from Olivier's observation, the main developer-manual ist 
updated when I make a change in developer-manual.adoc. Both html and pdf 
include the change.

It is not updated when I only change an included document like 
accounting.adoc. I think it would be good to recreate all files if they 
have chnaged or not. If I'm not wrong, both SVN and Git notice if a file 
has not be changed even if it is rewritten so it should be no problem.

I think this is a good starting point, more pints might come up if we 
use it more intensely.

Thanks,

Michael


Am 21.02.18 um 14:08 schrieb Olivier Heintz:
> Thank you for the work, Taher
>
> I have played with it and merge with my tests.
> Currently, I have start from Accounting_Agreement, convert from docbook and update and
> test renderer by both your gradle task and by AsciidocFx html button
>
> With a lot of include, result html file would be very large and in some case it will be good to be able to put a link in place
> of include. Currenlty the generateOfbizDocumentation task doesn't generate file for doc in component even if the adoc file is
> not in the _include directory.
>
> Just for information: With AsciidocFx (I have understood it use asciidoctor for generate html file, but I'm not sure)
> it's not necessary to say include file is in _include directory, it read both in the current directory and in the _include one.
> The generateOfbizDocumentation task doesn't use the same rule, we should say explicitly it's in the _include directory.
>
> The main "malfunction" of the generateOfbizDocumentation task is that it not re-generate the html file if it already exist
> even if the main adoc file was modified. So it's needed to remove it manually before call generateOfbizDocumentation.
>
> Thank you for your usage of leveloffset, it's generated by docbook conversion, but now I understand how it works ;-)
>
>
> Olivier
>
> Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit :
>> Hello documentation team and everyone
>>
>> I have created a slightly modified design of the documentation
>> framework with some sample contents in [1]. I highlight the changes
>> below:
>> - Created a new top-level directory called "docs/asciidoc". The reason
>> is so that we have more than one possible manual.
>> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
>> - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc
>> - Created a sample document in the accounting component to show how
>> documents are linked together.
>> - Used a special directive called "leveloffset" in the include
>> directive. This directive shifts the headers of the included document
>> (H2 becomes H3, and so on) so that sub-sections can be published
>> separately.
>> - Created a task called generateOfbizDocumentation to generate the
>> documentation (both PDF and HTML) for framework + core apps
>> - Created a task called generatePluginDocumentation
>> -PpluginId=whatever to generate the documentation for a single plugin.
>>
>> That's it. It's simple, easy to understand and I think you might like
>> it. Any feedback is welcome, and I'll talk to you soon over Skype.
>>
>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>
>> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
>>> Hi Taher
>>>
>>> I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed.
>>>
>>> We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!).
>>>
>>> My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-)
>>>
>>> Thanks
>>> Sharan
>>>
>>> On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com> wrote:
>>>> Like Michael I think it is also a minor point. The reason I chose this
>>>> structure is because it is the default one for asciidoctor and is flexible
>>>> for the future, so Paul also makes a good point. Any structure is fine by
>>>> me, the real important work is getting the documentation right which is
>>>> very exciting to me.
>>>>
>>>> I will create a patch soon for a base level structure and publishing
>>>> options for both HTML and PDF. It would be fantastic if we can unify _all_
>>>> of our documentation here including stuff currently in the wiki. This way
>>>> any changes to code are reflected (probably in the same commit) with the
>>>> relevant documentation.
>>>>
>>>> I think we should start to consider maybe forming a team willing to help.
>>>> This is a big, but extremely important thing to have. If we do this right
>>>> then I think adoption rates would increase and our community would get
>>>> larger.
>>>>
>>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de> wrote:
>>>>
>>>> Hi Paul,
>>>>
>>>> this is only a minor point for me, it just saves one folder/structure level.
>>>>
>>>> If we want to stay open for other documentation frameworks in the future,
>>>> it might be better to keep the proposed structure.
>>>>
>>>> Best regards,
>>>>
>>>> Michael
>>>>
>>>>
>>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>>>>
>>>> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de> wrote:
>>>>>
>>>>> with a small modification: I don't think we'll need a two-folder structure
>>>>>> /docs/asciidoc, only /docs should be sufficient, no?
>>>>>>
>>>>>> Hi Michael,
>>>>> We have streamlined the build system in other places by having folders for
>>>>> the source language: groovyScripts, minilang, src/main/java .
>>>>>
>>>>> It means Groovy and other build tools can have default rules for what to do
>>>>> with the contents of a language folder, and allows for the possibility of
>>>>> other languages in future if necessary.
>>>>>
>>>>> The extra layer is only a minor nuisance. I think I'd prefer to keep it.
>>>>> What do you see as the disadvantages?
>>>>>
>>>>> Cheers
>>>>>
>>>>> Paul Foxworthy
>>>>>
>>>>>

Re: [Discussion] documentation framework for OFBiz

[Olivier Heintz <ho...@ofbizextra.org>]

Thank you for the work, Taher

I have played with it and merge with my tests.
Currently, I have start from Accounting_Agreement, convert from docbook and update and
test renderer by both your gradle task and by AsciidocFx html button

With a lot of include, result html file would be very large and in some case it will be good to be able to put a link in place
of include. Currenlty the generateOfbizDocumentation task doesn't generate file for doc in component even if the adoc file is
not in the _include directory.

Just for information: With AsciidocFx (I have understood it use asciidoctor for generate html file, but I'm not sure)
it's not necessary to say include file is in _include directory, it read both in the current directory and in the _include one.
The generateOfbizDocumentation task doesn't use the same rule, we should say explicitly it's in the _include directory.

The main "malfunction" of the generateOfbizDocumentation task is that it not re-generate the html file if it already exist
even if the main adoc file was modified. So it's needed to remove it manually before call generateOfbizDocumentation.

Thank you for your usage of leveloffset, it's generated by docbook conversion, but now I understand how it works ;-)


Olivier

Le 20/02/2018 à 17:48, Taher Alkhateeb a écrit :
> Hello documentation team and everyone
> 
> I have created a slightly modified design of the documentation
> framework with some sample contents in [1]. I highlight the changes
> below:
> - Created a new top-level directory called "docs/asciidoc". The reason
> is so that we have more than one possible manual.
> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
> - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc
> - Created a sample document in the accounting component to show how
> documents are linked together.
> - Used a special directive called "leveloffset" in the include
> directive. This directive shifts the headers of the included document
> (H2 becomes H3, and so on) so that sub-sections can be published
> separately.
> - Created a task called generateOfbizDocumentation to generate the
> documentation (both PDF and HTML) for framework + core apps
> - Created a task called generatePluginDocumentation
> -PpluginId=whatever to generate the documentation for a single plugin.
> 
> That's it. It's simple, easy to understand and I think you might like
> it. Any feedback is welcome, and I'll talk to you soon over Skype.
> 
> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
> 
> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
>> Hi Taher
>>
>> I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed.
>>
>> We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!).
>>
>> My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-)
>>
>> Thanks
>> Sharan
>>
>> On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com> wrote:
>>> Like Michael I think it is also a minor point. The reason I chose this
>>> structure is because it is the default one for asciidoctor and is flexible
>>> for the future, so Paul also makes a good point. Any structure is fine by
>>> me, the real important work is getting the documentation right which is
>>> very exciting to me.
>>>
>>> I will create a patch soon for a base level structure and publishing
>>> options for both HTML and PDF. It would be fantastic if we can unify _all_
>>> of our documentation here including stuff currently in the wiki. This way
>>> any changes to code are reflected (probably in the same commit) with the
>>> relevant documentation.
>>>
>>> I think we should start to consider maybe forming a team willing to help.
>>> This is a big, but extremely important thing to have. If we do this right
>>> then I think adoption rates would increase and our community would get
>>> larger.
>>>
>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de> wrote:
>>>
>>> Hi Paul,
>>>
>>> this is only a minor point for me, it just saves one folder/structure level.
>>>
>>> If we want to stay open for other documentation frameworks in the future,
>>> it might be better to keep the proposed structure.
>>>
>>> Best regards,
>>>
>>> Michael
>>>
>>>
>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>>>
>>> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de> wrote:
>>>>
>>>>
>>>> with a small modification: I don't think we'll need a two-folder structure
>>>>> /docs/asciidoc, only /docs should be sufficient, no?
>>>>>
>>>>> Hi Michael,
>>>>
>>>> We have streamlined the build system in other places by having folders for
>>>> the source language: groovyScripts, minilang, src/main/java .
>>>>
>>>> It means Groovy and other build tools can have default rules for what to do
>>>> with the contents of a language folder, and allows for the possibility of
>>>> other languages in future if necessary.
>>>>
>>>> The extra layer is only a minor nuisance. I think I'd prefer to keep it.
>>>> What do you see as the disadvantages?
>>>>
>>>> Cheers
>>>>
>>>> Paul Foxworthy
>>>>
>>>>
>>>
> 

Re: [Discussion] documentation framework for OFBiz

[Michael Brohl <mi...@ecomify.de>]

Great work, Taher,

thank you for the example setup. I'm going to play with it in the next 
days and provide my feedback.

Thanks,

Michael

Am 20.02.18 um 17:48 schrieb Taher Alkhateeb:
> Hello documentation team and everyone
>
> I have created a slightly modified design of the documentation
> framework with some sample contents in [1]. I highlight the changes
> below:
> - Created a new top-level directory called "docs/asciidoc". The reason
> is so that we have more than one possible manual.
> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
> - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc
> - Created a sample document in the accounting component to show how
> documents are linked together.
> - Used a special directive called "leveloffset" in the include
> directive. This directive shifts the headers of the included document
> (H2 becomes H3, and so on) so that sub-sections can be published
> separately.
> - Created a task called generateOfbizDocumentation to generate the
> documentation (both PDF and HTML) for framework + core apps
> - Created a task called generatePluginDocumentation
> -PpluginId=whatever to generate the documentation for a single plugin.
>
> That's it. It's simple, easy to understand and I think you might like
> it. Any feedback is welcome, and I'll talk to you soon over Skype.
>
> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>
> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
>> Hi Taher
>>
>> I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed.
>>
>> We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!).
>>
>> My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-)
>>
>> Thanks
>> Sharan
>>
>> On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com> wrote:
>>> Like Michael I think it is also a minor point. The reason I chose this
>>> structure is because it is the default one for asciidoctor and is flexible
>>> for the future, so Paul also makes a good point. Any structure is fine by
>>> me, the real important work is getting the documentation right which is
>>> very exciting to me.
>>>
>>> I will create a patch soon for a base level structure and publishing
>>> options for both HTML and PDF. It would be fantastic if we can unify _all_
>>> of our documentation here including stuff currently in the wiki. This way
>>> any changes to code are reflected (probably in the same commit) with the
>>> relevant documentation.
>>>
>>> I think we should start to consider maybe forming a team willing to help.
>>> This is a big, but extremely important thing to have. If we do this right
>>> then I think adoption rates would increase and our community would get
>>> larger.
>>>
>>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de> wrote:
>>>
>>> Hi Paul,
>>>
>>> this is only a minor point for me, it just saves one folder/structure level.
>>>
>>> If we want to stay open for other documentation frameworks in the future,
>>> it might be better to keep the proposed structure.
>>>
>>> Best regards,
>>>
>>> Michael
>>>
>>>
>>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>>>
>>> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de> wrote:
>>>>
>>>> with a small modification: I don't think we'll need a two-folder structure
>>>>> /docs/asciidoc, only /docs should be sufficient, no?
>>>>>
>>>>> Hi Michael,
>>>> We have streamlined the build system in other places by having folders for
>>>> the source language: groovyScripts, minilang, src/main/java .
>>>>
>>>> It means Groovy and other build tools can have default rules for what to do
>>>> with the contents of a language folder, and allows for the possibility of
>>>> other languages in future if necessary.
>>>>
>>>> The extra layer is only a minor nuisance. I think I'd prefer to keep it.
>>>> What do you see as the disadvantages?
>>>>
>>>> Cheers
>>>>
>>>> Paul Foxworthy
>>>>
>>>>

Re: [Discussion] documentation framework for OFBiz

[Jacques Le Roux <ja...@les7arts.com>]

\o/

Jacques


Le 28/01/2018 à 11:12, Taher Alkhateeb a écrit :
> Like Michael I think it is also a minor point. The reason I chose this
> structure is because it is the default one for asciidoctor and is flexible
> for the future, so Paul also makes a good point. Any structure is fine by
> me, the real important work is getting the documentation right which is
> very exciting to me.
>
> I will create a patch soon for a base level structure and publishing
> options for both HTML and PDF. It would be fantastic if we can unify _all_
> of our documentation here including stuff currently in the wiki. This way
> any changes to code are reflected (probably in the same commit) with the
> relevant documentation.
>
> I think we should start to consider maybe forming a team willing to help.
> This is a big, but extremely important thing to have. If we do this right
> then I think adoption rates would increase and our community would get
> larger.
>
> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de> wrote:
>
> Hi Paul,
>
> this is only a minor point for me, it just saves one folder/structure level.
>
> If we want to stay open for other documentation frameworks in the future,
> it might be better to keep the proposed structure.
>
> Best regards,
>
> Michael
>
>
> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>
> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de> wrote:
>>
>> with a small modification: I don't think we'll need a two-folder structure
>>> /docs/asciidoc, only /docs should be sufficient, no?
>>>
>>> Hi Michael,
>> We have streamlined the build system in other places by having folders for
>> the source language: groovyScripts, minilang, src/main/java .
>>
>> It means Groovy and other build tools can have default rules for what to do
>> with the contents of a language folder, and allows for the possibility of
>> other languages in future if necessary.
>>
>> The extra layer is only a minor nuisance. I think I'd prefer to keep it.
>> What do you see as the disadvantages?
>>
>> Cheers
>>
>> Paul Foxworthy
>>
>>

Re: [Discussion] documentation framework for OFBiz

[Sharan Foga <sh...@apache.org>]

Hi Taher

Thanks for the update. I'll try and take a look at this later today.

Thanks
Sharan

On 2018/02/20 16:48:13, Taher Alkhateeb <sl...@gmail.com> wrote: 
> Hello documentation team and everyone
> 
> I have created a slightly modified design of the documentation
> framework with some sample contents in [1]. I highlight the changes
> below:
> - Created a new top-level directory called "docs/asciidoc". The reason
> is so that we have more than one possible manual.
> - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
> - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc
> - Created a sample document in the accounting component to show how
> documents are linked together.
> - Used a special directive called "leveloffset" in the include
> directive. This directive shifts the headers of the included document
> (H2 becomes H3, and so on) so that sub-sections can be published
> separately.
> - Created a task called generateOfbizDocumentation to generate the
> documentation (both PDF and HTML) for framework + core apps
> - Created a task called generatePluginDocumentation
> -PpluginId=whatever to generate the documentation for a single plugin.
> 
> That's it. It's simple, easy to understand and I think you might like
> it. Any feedback is welcome, and I'll talk to you soon over Skype.
> 
> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
> 
> On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
> > Hi Taher
> >
> > I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed.
> >
> > We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!).
> >
> > My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-)
> >
> > Thanks
> > Sharan
> >
> > On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com> wrote:
> >> Like Michael I think it is also a minor point. The reason I chose this
> >> structure is because it is the default one for asciidoctor and is flexible
> >> for the future, so Paul also makes a good point. Any structure is fine by
> >> me, the real important work is getting the documentation right which is
> >> very exciting to me.
> >>
> >> I will create a patch soon for a base level structure and publishing
> >> options for both HTML and PDF. It would be fantastic if we can unify _all_
> >> of our documentation here including stuff currently in the wiki. This way
> >> any changes to code are reflected (probably in the same commit) with the
> >> relevant documentation.
> >>
> >> I think we should start to consider maybe forming a team willing to help.
> >> This is a big, but extremely important thing to have. If we do this right
> >> then I think adoption rates would increase and our community would get
> >> larger.
> >>
> >> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de> wrote:
> >>
> >> Hi Paul,
> >>
> >> this is only a minor point for me, it just saves one folder/structure level.
> >>
> >> If we want to stay open for other documentation frameworks in the future,
> >> it might be better to keep the proposed structure.
> >>
> >> Best regards,
> >>
> >> Michael
> >>
> >>
> >> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
> >>
> >> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de> wrote:
> >> >
> >> >
> >> > with a small modification: I don't think we'll need a two-folder structure
> >> >> /docs/asciidoc, only /docs should be sufficient, no?
> >> >>
> >> >> Hi Michael,
> >> >
> >> > We have streamlined the build system in other places by having folders for
> >> > the source language: groovyScripts, minilang, src/main/java .
> >> >
> >> > It means Groovy and other build tools can have default rules for what to do
> >> > with the contents of a language folder, and allows for the possibility of
> >> > other languages in future if necessary.
> >> >
> >> > The extra layer is only a minor nuisance. I think I'd prefer to keep it.
> >> > What do you see as the disadvantages?
> >> >
> >> > Cheers
> >> >
> >> > Paul Foxworthy
> >> >
> >> >
> >>
> 

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

Hello documentation team and everyone

I have created a slightly modified design of the documentation
framework with some sample contents in [1]. I highlight the changes
below:
- Created a new top-level directory called "docs/asciidoc". The reason
is so that we have more than one possible manual.
- Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc
- Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc
- Created a sample document in the accounting component to show how
documents are linked together.
- Used a special directive called "leveloffset" in the include
directive. This directive shifts the headers of the included document
(H2 becomes H3, and so on) so that sub-sections can be published
separately.
- Created a task called generateOfbizDocumentation to generate the
documentation (both PDF and HTML) for framework + core apps
- Created a task called generatePluginDocumentation
-PpluginId=whatever to generate the documentation for a single plugin.

That's it. It's simple, easy to understand and I think you might like
it. Any feedback is welcome, and I'll talk to you soon over Skype.

[1] https://issues.apache.org/jira/browse/OFBIZ-9873

On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sh...@apache.org> wrote:
> Hi Taher
>
> I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed.
>
> We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!).
>
> My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-)
>
> Thanks
> Sharan
>
> On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com> wrote:
>> Like Michael I think it is also a minor point. The reason I chose this
>> structure is because it is the default one for asciidoctor and is flexible
>> for the future, so Paul also makes a good point. Any structure is fine by
>> me, the real important work is getting the documentation right which is
>> very exciting to me.
>>
>> I will create a patch soon for a base level structure and publishing
>> options for both HTML and PDF. It would be fantastic if we can unify _all_
>> of our documentation here including stuff currently in the wiki. This way
>> any changes to code are reflected (probably in the same commit) with the
>> relevant documentation.
>>
>> I think we should start to consider maybe forming a team willing to help.
>> This is a big, but extremely important thing to have. If we do this right
>> then I think adoption rates would increase and our community would get
>> larger.
>>
>> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de> wrote:
>>
>> Hi Paul,
>>
>> this is only a minor point for me, it just saves one folder/structure level.
>>
>> If we want to stay open for other documentation frameworks in the future,
>> it might be better to keep the proposed structure.
>>
>> Best regards,
>>
>> Michael
>>
>>
>> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
>>
>> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de> wrote:
>> >
>> >
>> > with a small modification: I don't think we'll need a two-folder structure
>> >> /docs/asciidoc, only /docs should be sufficient, no?
>> >>
>> >> Hi Michael,
>> >
>> > We have streamlined the build system in other places by having folders for
>> > the source language: groovyScripts, minilang, src/main/java .
>> >
>> > It means Groovy and other build tools can have default rules for what to do
>> > with the contents of a language folder, and allows for the possibility of
>> > other languages in future if necessary.
>> >
>> > The extra layer is only a minor nuisance. I think I'd prefer to keep it.
>> > What do you see as the disadvantages?
>> >
>> > Cheers
>> >
>> > Paul Foxworthy
>> >
>> >
>>

Re: [Discussion] documentation framework for OFBiz

[Sharan Foga <sh...@apache.org>]

Hi Taher

I think a documentation team would be a great idea. There are people that have indicated that they'd like to help out with documentation tasks on the user list so that is where I'd recruit some people from. As long as people know what they need to do to create the patches then it will become a funnel process of getting it committed.

We need a plan to consolidate the information sitting in the wiki and getting it put into the documentation framework (and this work will then significantly clear up the wiki!).

My availability is pretty bad this week so hope to pick this up again or start the recruitment campaign next week :-)

Thanks
Sharan

On 2018/01/28 10:12:41, Taher Alkhateeb <sl...@gmail.com> wrote: 
> Like Michael I think it is also a minor point. The reason I chose this
> structure is because it is the default one for asciidoctor and is flexible
> for the future, so Paul also makes a good point. Any structure is fine by
> me, the real important work is getting the documentation right which is
> very exciting to me.
> 
> I will create a patch soon for a base level structure and publishing
> options for both HTML and PDF. It would be fantastic if we can unify _all_
> of our documentation here including stuff currently in the wiki. This way
> any changes to code are reflected (probably in the same commit) with the
> relevant documentation.
> 
> I think we should start to consider maybe forming a team willing to help.
> This is a big, but extremely important thing to have. If we do this right
> then I think adoption rates would increase and our community would get
> larger.
> 
> On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de> wrote:
> 
> Hi Paul,
> 
> this is only a minor point for me, it just saves one folder/structure level.
> 
> If we want to stay open for other documentation frameworks in the future,
> it might be better to keep the proposed structure.
> 
> Best regards,
> 
> Michael
> 
> 
> Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
> 
> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de> wrote:
> >
> >
> > with a small modification: I don't think we'll need a two-folder structure
> >> /docs/asciidoc, only /docs should be sufficient, no?
> >>
> >> Hi Michael,
> >
> > We have streamlined the build system in other places by having folders for
> > the source language: groovyScripts, minilang, src/main/java .
> >
> > It means Groovy and other build tools can have default rules for what to do
> > with the contents of a language folder, and allows for the possibility of
> > other languages in future if necessary.
> >
> > The extra layer is only a minor nuisance. I think I'd prefer to keep it.
> > What do you see as the disadvantages?
> >
> > Cheers
> >
> > Paul Foxworthy
> >
> >
> 

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

Like Michael I think it is also a minor point. The reason I chose this
structure is because it is the default one for asciidoctor and is flexible
for the future, so Paul also makes a good point. Any structure is fine by
me, the real important work is getting the documentation right which is
very exciting to me.

I will create a patch soon for a base level structure and publishing
options for both HTML and PDF. It would be fantastic if we can unify _all_
of our documentation here including stuff currently in the wiki. This way
any changes to code are reflected (probably in the same commit) with the
relevant documentation.

I think we should start to consider maybe forming a team willing to help.
This is a big, but extremely important thing to have. If we do this right
then I think adoption rates would increase and our community would get
larger.

On Jan 28, 2018 12:19 PM, "Michael Brohl" <mi...@ecomify.de> wrote:

Hi Paul,

this is only a minor point for me, it just saves one folder/structure level.

If we want to stay open for other documentation frameworks in the future,
it might be better to keep the proposed structure.

Best regards,

Michael


Am 28.01.18 um 02:54 schrieb Paul Foxworthy:

On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de> wrote:
>
>
> with a small modification: I don't think we'll need a two-folder structure
>> /docs/asciidoc, only /docs should be sufficient, no?
>>
>> Hi Michael,
>
> We have streamlined the build system in other places by having folders for
> the source language: groovyScripts, minilang, src/main/java .
>
> It means Groovy and other build tools can have default rules for what to do
> with the contents of a language folder, and allows for the possibility of
> other languages in future if necessary.
>
> The extra layer is only a minor nuisance. I think I'd prefer to keep it.
> What do you see as the disadvantages?
>
> Cheers
>
> Paul Foxworthy
>
>

Re: [Discussion] documentation framework for OFBiz

[Michael Brohl <mi...@ecomify.de>]

Hi Paul,

this is only a minor point for me, it just saves one folder/structure level.

If we want to stay open for other documentation frameworks in the 
future, it might be better to keep the proposed structure.

Best regards,

Michael


Am 28.01.18 um 02:54 schrieb Paul Foxworthy:
> On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de> wrote:
>
>
>> with a small modification: I don't think we'll need a two-folder structure
>> /docs/asciidoc, only /docs should be sufficient, no?
>>
> Hi Michael,
>
> We have streamlined the build system in other places by having folders for
> the source language: groovyScripts, minilang, src/main/java .
>
> It means Groovy and other build tools can have default rules for what to do
> with the contents of a language folder, and allows for the possibility of
> other languages in future if necessary.
>
> The extra layer is only a minor nuisance. I think I'd prefer to keep it.
> What do you see as the disadvantages?
>
> Cheers
>
> Paul Foxworthy
>

Re: [Discussion] documentation framework for OFBiz

[Paul Foxworthy <pa...@cohsoft.com.au>]

On 26 January 2018 at 19:53, Michael Brohl <mi...@ecomify.de> wrote:


> with a small modification: I don't think we'll need a two-folder structure
> /docs/asciidoc, only /docs should be sufficient, no?
>

Hi Michael,

We have streamlined the build system in other places by having folders for
the source language: groovyScripts, minilang, src/main/java .

It means Groovy and other build tools can have default rules for what to do
with the contents of a language folder, and allows for the possibility of
other languages in future if necessary.

The extra layer is only a minor nuisance. I think I'd prefer to keep it.
What do you see as the disadvantages?

Cheers

Paul Foxworthy

-- 
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Australia

Phone: +61 3 9585 6788
Web: http://www.coherentsoftware.com.au/
Email: info@coherentsoftware.com.au

Re: [Discussion] documentation framework for OFBiz

[Michael Brohl <mi...@ecomify.de>]

+1

with a small modification: I don't think we'll need a two-folder 
structure /docs/asciidoc, only /docs should be sufficient, no?

Regards,

Michael


Am 25.01.18 um 15:00 schrieb Sharan Foga:
> Hi Taher
>
> The picture helps :-) I had to do a bit of a double-take but I get it now and a big +1
>
> I like what you are suggesting – very nice. It is not entirely following the  menu structure (which is good) instead it is looking at the individual topics. This means that we can make the main document flow a lot easier than simply following what we have in the menus. (e.g We know that you can get to the same place from by different routes on the menus and screens, so focussing on the topic itself will help that.)
>
> I think this will give us the flexibility we need. A standard structure helps people know where to put things.
>
> Thanks
> Sharan
>
> On 2018/01/25 11:37:02, Taher Alkhateeb <sl...@gmail.com> wrote:
>> Hi Everyone,
>>
>> So after a little bit of thinking, I came up with an example file
>> structure for OFBiz documentation which is listed below. The full
>> OFBiz manual simply points to all the parts in applications,
>> framework, and themes to complete the documentation. Any ideas or
>> feedback is welcomed.
>>
>> A few points to note:
>> - Gradle by default ignores any files in the _include sub directory
>> and so it will only publish the outer document.
>> - This way, we can publish per component (in isolation) or the whole
>> documentation by simply publishing the ofbiz-manual.adoc file
>> - We can further branch out the documentation as needed.
>>
>> ofbiz
>> ├── applications
>> │   ├── accounting
>> │   │   └── src
>> │   │       └── docs
>> │   │           └── asciidoc
>> │   │               ├── accounting.adoc
>> │   │               └── _include
>> │   │                   ├── accounting-intro.adoc
>> │   │                   ├── budgets.adoc
>> │   │                   ├── invoices.adoc
>> │   │                   ├── payments.adoc
>> │   │                   └── understanding-general-ledger.adoc
>> │   └── humanres
>> │       └── src
>> │           └── docs
>> │               └── asciidoc
>> │                   ├── humanres.adoc
>> │                   └── _include
>> │                       ├── employee-evaluations.adoc
>> │                       ├── human-resources-intro.adoc
>> │                       └── punch-in-punch-out.adoc
>> ├── framework
>> │   ├── base
>> │   │   └── src
>> │   │       └── docs
>> │   │           └── asciidoc
>> │   │               ├── base.adoc
>> │   │               └── _include
>> │   │                   ├── containers.adoc
>> │   │                   ├── framework-intro.adoc
>> │   │                   └── loading-components.adoc
>> │   ├── entity
>> │   │   └── src
>> │   │       └── docs
>> │   │           └── asciidoc
>> │   │               ├── entity.adoc
>> │   │               └── _include
>> │   │                   ├── entity-conditions-api.adoc
>> │   │                   ├── entity-engine-intro.adoc
>> │   │                   └── mapping-new-database.adoc
>> │   └── widget
>> │       └── src
>> │           └── docs
>> │               └── asciidoc
>> │                   ├── _include
>> │                   │   ├── form-widgets.adoc
>> │                   │   ├── screen-widgets.adoc
>> │                   │   └── widget-system-intro.adoc
>> │                   └── widget.adoc
>> ├── ofbiz-manual.adoc
>> ├── plugins
>> │   └── example
>> │       └── src
>> │           └── docs
>> │               └── asciidoc
>> │                   ├── example.adoc
>> │                   └── _include
>> │                       ├── example-intro.adoc
>> │                       └── extending-example-widgets.adoc
>> └── themes
>>      └── common-theme
>>          └── src
>>              └── docs
>>                  └── asciidoc
>>                      ├── common-theme.adoc
>>                      └── _include
>>                          ├── ofbiz-themes-intro.adoc
>>                          ├── web-assets.adoc
>>                          └── why-common-theme.adoc
>>
>> On Fri, Jan 19, 2018 at 4:27 PM, Jacques Le Roux
>> <ja...@les7arts.com> wrote:
>>> Hi Sharan, Craig,
>>>
>>> We already have a document that consolidates many smaller documents into
>>> itself, but as said Sharan in another reply it got not much attention
>>> because it was maybe not statisfying (though had interesting info)
>>>
>>> https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML
>>>
>>> My 2cts
>>>
>>> Jacques
>>>
>>>
>>>
>>> Le 18/01/2018 à 13:31, Sharan Foga a écrit :
>>>> Hi Craig
>>>>
>>>> Generally I was thinking about how it was going to be laid out. So if you
>>>> think about one big consolidated OFBiz Guide that contains both technical
>>>> and user guide info, then what would that look like? How would you structure
>>>> the one consolidated output?
>>>>
>>>> I don't think that it would necessarily need to mirror the exact structure
>>>> of the menus - it just depends on how it's linked to the overall process (if
>>>> you are thinking user docs). Also some of the things we need to write about
>>>> won't appear anywhere in the menus - so we'll need a general place for that.
>>>>
>>>> My comment was also about the format of each of the source documents to
>>>> ensure consistency. Since we are going to be consolidating many smaller
>>>> documents into one big one, so it needs to look like they belong together.
>>>>
>>>> Hope that makes it clearer.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-17 16:08, Craig Parker <cr...@fossfolks.com> wrote:
>>>>> I think the doc structure ought to mirror the menu in the software, or
>>>>> are you talking about how a doc itself is laid out?
>>>>>
>>>>>
>>>>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>>>>> Hi Taher
>>>>>>
>>>>>> Great work! I tried it out and found it simple and easy to use (and
>>>>>> write!). When can we start writing ? :-)
>>>>>>
>>>>>> I was thinking to start with basic descriptions of each of the
>>>>>> applications, then see how it evolves from there. We can maybe recover some
>>>>>> documentation content from various sources including our existing online
>>>>>> help system and the wiki.
>>>>>>
>>>>>> The documentation structure will maybe need some thought, and we may
>>>>>> need to sort out some common template or guidelines around it.
>>>>>>
>>>>>> Thanks
>>>>>> Sharan
>>>>>>
>>>>>> On 2018-01-14 12:33, "Sharan Foga"<sh...@apache.org> wrote:
>>>>>>> Excellent news Taher!
>>>>>>>
>>>>>>> Thanks very much for your effort on this. I'll aim to try it out this
>>>>>>> week and come back with any feedback.
>>>>>>>
>>>>>>> Thanks
>>>>>>> Sharan
>>>>>>>
>>>>>>> On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com>
>>>>>>> wrote:
>>>>>>>> Hello everyone,
>>>>>>>>
>>>>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>>>>> directory and putting files inside.
>>>>>>>>
>>>>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>>>>> of it. Please review it and tell me if you like the general design.
>>>>>>>>
>>>>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>>>>
>>>>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>>>>> <sl...@gmail.com> wrote:
>>>>>>>>> Hello Folks,
>>>>>>>>>
>>>>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>>>>> the best way to write and distribute documentation, and I think most
>>>>>>>>> of that is applicable to OFBiz.
>>>>>>>>>
>>>>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>>>>
>>>>>>>>> - The documentation language to use is Asciidoc
>>>>>>>>> - The documentation tool is Asciidoctor
>>>>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>>>>> - The only place where we write documentation is inside the code base
>>>>>>>>> - Every component contains its own documentation
>>>>>>>>> - General documentation goes to either a standalone directory or a
>>>>>>>>> generic component like common or base
>>>>>>>>> - As much as possible, documentation files are small and focused on
>>>>>>>>> one topic. And then other longer documents are constructed from these
>>>>>>>>> snippets of documentation.
>>>>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>>>>> help system, instead it just renders generated HTML.
>>>>>>>>>
>>>>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>>>>> that update is no longer a painful grepping process.
>>>>>>>>>
>>>>>>>>> Would love to hear your thoughts on this.
>>>>>>>>>
>>>>>>>>> Cheers,
>>>>>>>>>
>>>>>>>>> Taher Alkhateeb
>>>>>

Re: [Discussion] documentation framework for OFBiz

[Sharan Foga <sh...@apache.org>]

Hi Taher

The picture helps :-) I had to do a bit of a double-take but I get it now and a big +1

I like what you are suggesting – very nice. It is not entirely following the  menu structure (which is good) instead it is looking at the individual topics. This means that we can make the main document flow a lot easier than simply following what we have in the menus. (e.g We know that you can get to the same place from by different routes on the menus and screens, so focussing on the topic itself will help that.)

I think this will give us the flexibility we need. A standard structure helps people know where to put things.

Thanks
Sharan

On 2018/01/25 11:37:02, Taher Alkhateeb <sl...@gmail.com> wrote: 
> Hi Everyone,
> 
> So after a little bit of thinking, I came up with an example file
> structure for OFBiz documentation which is listed below. The full
> OFBiz manual simply points to all the parts in applications,
> framework, and themes to complete the documentation. Any ideas or
> feedback is welcomed.
> 
> A few points to note:
> - Gradle by default ignores any files in the _include sub directory
> and so it will only publish the outer document.
> - This way, we can publish per component (in isolation) or the whole
> documentation by simply publishing the ofbiz-manual.adoc file
> - We can further branch out the documentation as needed.
> 
> ofbiz
> ├── applications
> │   ├── accounting
> │   │   └── src
> │   │       └── docs
> │   │           └── asciidoc
> │   │               ├── accounting.adoc
> │   │               └── _include
> │   │                   ├── accounting-intro.adoc
> │   │                   ├── budgets.adoc
> │   │                   ├── invoices.adoc
> │   │                   ├── payments.adoc
> │   │                   └── understanding-general-ledger.adoc
> │   └── humanres
> │       └── src
> │           └── docs
> │               └── asciidoc
> │                   ├── humanres.adoc
> │                   └── _include
> │                       ├── employee-evaluations.adoc
> │                       ├── human-resources-intro.adoc
> │                       └── punch-in-punch-out.adoc
> ├── framework
> │   ├── base
> │   │   └── src
> │   │       └── docs
> │   │           └── asciidoc
> │   │               ├── base.adoc
> │   │               └── _include
> │   │                   ├── containers.adoc
> │   │                   ├── framework-intro.adoc
> │   │                   └── loading-components.adoc
> │   ├── entity
> │   │   └── src
> │   │       └── docs
> │   │           └── asciidoc
> │   │               ├── entity.adoc
> │   │               └── _include
> │   │                   ├── entity-conditions-api.adoc
> │   │                   ├── entity-engine-intro.adoc
> │   │                   └── mapping-new-database.adoc
> │   └── widget
> │       └── src
> │           └── docs
> │               └── asciidoc
> │                   ├── _include
> │                   │   ├── form-widgets.adoc
> │                   │   ├── screen-widgets.adoc
> │                   │   └── widget-system-intro.adoc
> │                   └── widget.adoc
> ├── ofbiz-manual.adoc
> ├── plugins
> │   └── example
> │       └── src
> │           └── docs
> │               └── asciidoc
> │                   ├── example.adoc
> │                   └── _include
> │                       ├── example-intro.adoc
> │                       └── extending-example-widgets.adoc
> └── themes
>     └── common-theme
>         └── src
>             └── docs
>                 └── asciidoc
>                     ├── common-theme.adoc
>                     └── _include
>                         ├── ofbiz-themes-intro.adoc
>                         ├── web-assets.adoc
>                         └── why-common-theme.adoc
> 
> On Fri, Jan 19, 2018 at 4:27 PM, Jacques Le Roux
> <ja...@les7arts.com> wrote:
> > Hi Sharan, Craig,
> >
> > We already have a document that consolidates many smaller documents into
> > itself, but as said Sharan in another reply it got not much attention
> > because it was maybe not statisfying (though had interesting info)
> >
> > https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML
> >
> > My 2cts
> >
> > Jacques
> >
> >
> >
> > Le 18/01/2018 à 13:31, Sharan Foga a écrit :
> >>
> >> Hi Craig
> >>
> >> Generally I was thinking about how it was going to be laid out. So if you
> >> think about one big consolidated OFBiz Guide that contains both technical
> >> and user guide info, then what would that look like? How would you structure
> >> the one consolidated output?
> >>
> >> I don't think that it would necessarily need to mirror the exact structure
> >> of the menus - it just depends on how it's linked to the overall process (if
> >> you are thinking user docs). Also some of the things we need to write about
> >> won't appear anywhere in the menus - so we'll need a general place for that.
> >>
> >> My comment was also about the format of each of the source documents to
> >> ensure consistency. Since we are going to be consolidating many smaller
> >> documents into one big one, so it needs to look like they belong together.
> >>
> >> Hope that makes it clearer.
> >>
> >> Thanks
> >> Sharan
> >>
> >> On 2018-01-17 16:08, Craig Parker <cr...@fossfolks.com> wrote:
> >>>
> >>> I think the doc structure ought to mirror the menu in the software, or
> >>> are you talking about how a doc itself is laid out?
> >>>
> >>>
> >>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
> >>>>
> >>>> Hi Taher
> >>>>
> >>>> Great work! I tried it out and found it simple and easy to use (and
> >>>> write!). When can we start writing ? :-)
> >>>>
> >>>> I was thinking to start with basic descriptions of each of the
> >>>> applications, then see how it evolves from there. We can maybe recover some
> >>>> documentation content from various sources including our existing online
> >>>> help system and the wiki.
> >>>>
> >>>> The documentation structure will maybe need some thought, and we may
> >>>> need to sort out some common template or guidelines around it.
> >>>>
> >>>> Thanks
> >>>> Sharan
> >>>>
> >>>> On 2018-01-14 12:33, "Sharan Foga"<sh...@apache.org> wrote:
> >>>>>
> >>>>> Excellent news Taher!
> >>>>>
> >>>>> Thanks very much for your effort on this. I'll aim to try it out this
> >>>>> week and come back with any feedback.
> >>>>>
> >>>>> Thanks
> >>>>> Sharan
> >>>>>
> >>>>> On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com>
> >>>>> wrote:
> >>>>>>
> >>>>>> Hello everyone,
> >>>>>>
> >>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
> >>>>>> have a small patch in [1] that provides the PoC for integrating
> >>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
> >>>>>> instructions on how to run it. Essentially, this allows you to create
> >>>>>> documentation for any component by simply creating a src/docs/asciidoc
> >>>>>> directory and putting files inside.
> >>>>>>
> >>>>>> This solution is flexible and allows us to build bigger designs on top
> >>>>>> of it. Please review it and tell me if you like the general design.
> >>>>>>
> >>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
> >>>>>>
> >>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
> >>>>>> <sl...@gmail.com> wrote:
> >>>>>>>
> >>>>>>> Hello Folks,
> >>>>>>>
> >>>>>>> We've had this discussion multiple times in the past, but I think I
> >>>>>>> have a more concrete idea this time for solving this problem. In the
> >>>>>>> past few weeks we've been working internally in Pythys to figure out
> >>>>>>> the best way to write and distribute documentation, and I think most
> >>>>>>> of that is applicable to OFBiz.
> >>>>>>>
> >>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
> >>>>>>>
> >>>>>>> - The documentation language to use is Asciidoc
> >>>>>>> - The documentation tool is Asciidoctor
> >>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
> >>>>>>> plugin (not the OFBiz framework or anything else).
> >>>>>>> - The only place where we write documentation is inside the code base
> >>>>>>> - Every component contains its own documentation
> >>>>>>> - General documentation goes to either a standalone directory or a
> >>>>>>> generic component like common or base
> >>>>>>> - As much as possible, documentation files are small and focused on
> >>>>>>> one topic. And then other longer documents are constructed from these
> >>>>>>> snippets of documentation.
> >>>>>>> - We publish to all formats including PDF for users, or HTML for
> >>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
> >>>>>>> help system, instead it just renders generated HTML.
> >>>>>>>
> >>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
> >>>>>>> (like markdown) but also modular (like docbook and dita). It's also
> >>>>>>> neat that you can sprinkle variables all around in your document so
> >>>>>>> that update is no longer a painful grepping process.
> >>>>>>>
> >>>>>>> Would love to hear your thoughts on this.
> >>>>>>>
> >>>>>>> Cheers,
> >>>>>>>
> >>>>>>> Taher Alkhateeb
> >>>
> >>>
> >
> 

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

Hi Everyone,

So after a little bit of thinking, I came up with an example file
structure for OFBiz documentation which is listed below. The full
OFBiz manual simply points to all the parts in applications,
framework, and themes to complete the documentation. Any ideas or
feedback is welcomed.

A few points to note:
- Gradle by default ignores any files in the _include sub directory
and so it will only publish the outer document.
- This way, we can publish per component (in isolation) or the whole
documentation by simply publishing the ofbiz-manual.adoc file
- We can further branch out the documentation as needed.

ofbiz
├── applications
│   ├── accounting
│   │   └── src
│   │       └── docs
│   │           └── asciidoc
│   │               ├── accounting.adoc
│   │               └── _include
│   │                   ├── accounting-intro.adoc
│   │                   ├── budgets.adoc
│   │                   ├── invoices.adoc
│   │                   ├── payments.adoc
│   │                   └── understanding-general-ledger.adoc
│   └── humanres
│       └── src
│           └── docs
│               └── asciidoc
│                   ├── humanres.adoc
│                   └── _include
│                       ├── employee-evaluations.adoc
│                       ├── human-resources-intro.adoc
│                       └── punch-in-punch-out.adoc
├── framework
│   ├── base
│   │   └── src
│   │       └── docs
│   │           └── asciidoc
│   │               ├── base.adoc
│   │               └── _include
│   │                   ├── containers.adoc
│   │                   ├── framework-intro.adoc
│   │                   └── loading-components.adoc
│   ├── entity
│   │   └── src
│   │       └── docs
│   │           └── asciidoc
│   │               ├── entity.adoc
│   │               └── _include
│   │                   ├── entity-conditions-api.adoc
│   │                   ├── entity-engine-intro.adoc
│   │                   └── mapping-new-database.adoc
│   └── widget
│       └── src
│           └── docs
│               └── asciidoc
│                   ├── _include
│                   │   ├── form-widgets.adoc
│                   │   ├── screen-widgets.adoc
│                   │   └── widget-system-intro.adoc
│                   └── widget.adoc
├── ofbiz-manual.adoc
├── plugins
│   └── example
│       └── src
│           └── docs
│               └── asciidoc
│                   ├── example.adoc
│                   └── _include
│                       ├── example-intro.adoc
│                       └── extending-example-widgets.adoc
└── themes
    └── common-theme
        └── src
            └── docs
                └── asciidoc
                    ├── common-theme.adoc
                    └── _include
                        ├── ofbiz-themes-intro.adoc
                        ├── web-assets.adoc
                        └── why-common-theme.adoc

On Fri, Jan 19, 2018 at 4:27 PM, Jacques Le Roux
<ja...@les7arts.com> wrote:
> Hi Sharan, Craig,
>
> We already have a document that consolidates many smaller documents into
> itself, but as said Sharan in another reply it got not much attention
> because it was maybe not statisfying (though had interesting info)
>
> https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML
>
> My 2cts
>
> Jacques
>
>
>
> Le 18/01/2018 à 13:31, Sharan Foga a écrit :
>>
>> Hi Craig
>>
>> Generally I was thinking about how it was going to be laid out. So if you
>> think about one big consolidated OFBiz Guide that contains both technical
>> and user guide info, then what would that look like? How would you structure
>> the one consolidated output?
>>
>> I don't think that it would necessarily need to mirror the exact structure
>> of the menus - it just depends on how it's linked to the overall process (if
>> you are thinking user docs). Also some of the things we need to write about
>> won't appear anywhere in the menus - so we'll need a general place for that.
>>
>> My comment was also about the format of each of the source documents to
>> ensure consistency. Since we are going to be consolidating many smaller
>> documents into one big one, so it needs to look like they belong together.
>>
>> Hope that makes it clearer.
>>
>> Thanks
>> Sharan
>>
>> On 2018-01-17 16:08, Craig Parker <cr...@fossfolks.com> wrote:
>>>
>>> I think the doc structure ought to mirror the menu in the software, or
>>> are you talking about how a doc itself is laid out?
>>>
>>>
>>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>>>
>>>> Hi Taher
>>>>
>>>> Great work! I tried it out and found it simple and easy to use (and
>>>> write!). When can we start writing ? :-)
>>>>
>>>> I was thinking to start with basic descriptions of each of the
>>>> applications, then see how it evolves from there. We can maybe recover some
>>>> documentation content from various sources including our existing online
>>>> help system and the wiki.
>>>>
>>>> The documentation structure will maybe need some thought, and we may
>>>> need to sort out some common template or guidelines around it.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-14 12:33, "Sharan Foga"<sh...@apache.org> wrote:
>>>>>
>>>>> Excellent news Taher!
>>>>>
>>>>> Thanks very much for your effort on this. I'll aim to try it out this
>>>>> week and come back with any feedback.
>>>>>
>>>>> Thanks
>>>>> Sharan
>>>>>
>>>>> On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com>
>>>>> wrote:
>>>>>>
>>>>>> Hello everyone,
>>>>>>
>>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>>> directory and putting files inside.
>>>>>>
>>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>>> of it. Please review it and tell me if you like the general design.
>>>>>>
>>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>>
>>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>>> <sl...@gmail.com> wrote:
>>>>>>>
>>>>>>> Hello Folks,
>>>>>>>
>>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>>> the best way to write and distribute documentation, and I think most
>>>>>>> of that is applicable to OFBiz.
>>>>>>>
>>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>>
>>>>>>> - The documentation language to use is Asciidoc
>>>>>>> - The documentation tool is Asciidoctor
>>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>>> - The only place where we write documentation is inside the code base
>>>>>>> - Every component contains its own documentation
>>>>>>> - General documentation goes to either a standalone directory or a
>>>>>>> generic component like common or base
>>>>>>> - As much as possible, documentation files are small and focused on
>>>>>>> one topic. And then other longer documents are constructed from these
>>>>>>> snippets of documentation.
>>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>>> help system, instead it just renders generated HTML.
>>>>>>>
>>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>>> that update is no longer a painful grepping process.
>>>>>>>
>>>>>>> Would love to hear your thoughts on this.
>>>>>>>
>>>>>>> Cheers,
>>>>>>>
>>>>>>> Taher Alkhateeb
>>>
>>>
>

Re: [Discussion] documentation framework for OFBiz

[Jacques Le Roux <ja...@les7arts.com>]

Hi Sharan, Craig,

We already have a document that consolidates many smaller documents into itself, but as said Sharan in another reply it got not much attention because 
it was maybe not statisfying (though had interesting info)

https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML

My 2cts

Jacques


Le 18/01/2018 à 13:31, Sharan Foga a écrit :
> Hi Craig
>
> Generally I was thinking about how it was going to be laid out. So if you think about one big consolidated OFBiz Guide that contains both technical and user guide info, then what would that look like? How would you structure the one consolidated output?
>
> I don't think that it would necessarily need to mirror the exact structure of the menus - it just depends on how it's linked to the overall process (if you are thinking user docs). Also some of the things we need to write about won't appear anywhere in the menus - so we'll need a general place for that.
>
> My comment was also about the format of each of the source documents to ensure consistency. Since we are going to be consolidating many smaller documents into one big one, so it needs to look like they belong together.
>
> Hope that makes it clearer.
>
> Thanks
> Sharan
>
> On 2018-01-17 16:08, Craig Parker <cr...@fossfolks.com> wrote:
>> I think the doc structure ought to mirror the menu in the software, or
>> are you talking about how a doc itself is laid out?
>>
>>
>> On 01/17/2018 09:25 AM, Sharan Foga wrote:
>>> Hi Taher
>>>
>>> Great work! I tried it out and found it simple and easy to use (and write!). When can we start writing ? :-)
>>>
>>> I was thinking to start with basic descriptions of each of the applications, then see how it evolves from there. We can maybe recover some documentation content from various sources including our existing online help system and the wiki.
>>>
>>> The documentation structure will maybe need some thought, and we may need to sort out some common template or guidelines around it.
>>>
>>> Thanks
>>> Sharan
>>>
>>> On 2018-01-14 12:33, "Sharan Foga"<sh...@apache.org> wrote:
>>>> Excellent news Taher!
>>>>
>>>> Thanks very much for your effort on this. I'll aim to try it out this week and come back with any feedback.
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>> On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com> wrote:
>>>>> Hello everyone,
>>>>>
>>>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>>>> have a small patch in [1] that provides the PoC for integrating
>>>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>>>> instructions on how to run it. Essentially, this allows you to create
>>>>> documentation for any component by simply creating a src/docs/asciidoc
>>>>> directory and putting files inside.
>>>>>
>>>>> This solution is flexible and allows us to build bigger designs on top
>>>>> of it. Please review it and tell me if you like the general design.
>>>>>
>>>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>>>
>>>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>>>> <sl...@gmail.com> wrote:
>>>>>> Hello Folks,
>>>>>>
>>>>>> We've had this discussion multiple times in the past, but I think I
>>>>>> have a more concrete idea this time for solving this problem. In the
>>>>>> past few weeks we've been working internally in Pythys to figure out
>>>>>> the best way to write and distribute documentation, and I think most
>>>>>> of that is applicable to OFBiz.
>>>>>>
>>>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>>>
>>>>>> - The documentation language to use is Asciidoc
>>>>>> - The documentation tool is Asciidoctor
>>>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>>>> plugin (not the OFBiz framework or anything else).
>>>>>> - The only place where we write documentation is inside the code base
>>>>>> - Every component contains its own documentation
>>>>>> - General documentation goes to either a standalone directory or a
>>>>>> generic component like common or base
>>>>>> - As much as possible, documentation files are small and focused on
>>>>>> one topic. And then other longer documents are constructed from these
>>>>>> snippets of documentation.
>>>>>> - We publish to all formats including PDF for users, or HTML for
>>>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>>>> help system, instead it just renders generated HTML.
>>>>>>
>>>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>>>> neat that you can sprinkle variables all around in your document so
>>>>>> that update is no longer a painful grepping process.
>>>>>>
>>>>>> Would love to hear your thoughts on this.
>>>>>>
>>>>>> Cheers,
>>>>>>
>>>>>> Taher Alkhateeb
>>

Re: [Discussion] documentation framework for OFBiz

[Sharan Foga <sh...@apache.org>]

Hi Craig

Generally I was thinking about how it was going to be laid out. So if you think about one big consolidated OFBiz Guide that contains both technical and user guide info, then what would that look like? How would you structure the one consolidated output? 

I don't think that it would necessarily need to mirror the exact structure of the menus - it just depends on how it's linked to the overall process (if you are thinking user docs). Also some of the things we need to write about won't appear anywhere in the menus - so we'll need a general place for that.

My comment was also about the format of each of the source documents to ensure consistency. Since we are going to be consolidating many smaller documents into one big one, so it needs to look like they belong together.

Hope that makes it clearer.

Thanks
Sharan

On 2018-01-17 16:08, Craig Parker <cr...@fossfolks.com> wrote: 
> I think the doc structure ought to mirror the menu in the software, or 
> are you talking about how a doc itself is laid out?
> 
> 
> On 01/17/2018 09:25 AM, Sharan Foga wrote:
> > Hi Taher
> >
> > Great work! I tried it out and found it simple and easy to use (and write!). When can we start writing ? :-)
> >
> > I was thinking to start with basic descriptions of each of the applications, then see how it evolves from there. We can maybe recover some documentation content from various sources including our existing online help system and the wiki.
> >
> > The documentation structure will maybe need some thought, and we may need to sort out some common template or guidelines around it.
> >
> > Thanks
> > Sharan
> >
> > On 2018-01-14 12:33, "Sharan Foga"<sh...@apache.org> wrote:
> >> Excellent news Taher!
> >>
> >> Thanks very much for your effort on this. I'll aim to try it out this week and come back with any feedback.
> >>
> >> Thanks
> >> Sharan
> >>
> >> On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com> wrote:
> >>> Hello everyone,
> >>>
> >>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
> >>> have a small patch in [1] that provides the PoC for integrating
> >>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
> >>> instructions on how to run it. Essentially, this allows you to create
> >>> documentation for any component by simply creating a src/docs/asciidoc
> >>> directory and putting files inside.
> >>>
> >>> This solution is flexible and allows us to build bigger designs on top
> >>> of it. Please review it and tell me if you like the general design.
> >>>
> >>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
> >>>
> >>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
> >>> <sl...@gmail.com> wrote:
> >>>> Hello Folks,
> >>>>
> >>>> We've had this discussion multiple times in the past, but I think I
> >>>> have a more concrete idea this time for solving this problem. In the
> >>>> past few weeks we've been working internally in Pythys to figure out
> >>>> the best way to write and distribute documentation, and I think most
> >>>> of that is applicable to OFBiz.
> >>>>
> >>>> In a nutshell, here is the idea (practically) for how to proceed:
> >>>>
> >>>> - The documentation language to use is Asciidoc
> >>>> - The documentation tool is Asciidoctor
> >>>> - Publishing happens through Gradle using the asciidoctor gradle
> >>>> plugin (not the OFBiz framework or anything else).
> >>>> - The only place where we write documentation is inside the code base
> >>>> - Every component contains its own documentation
> >>>> - General documentation goes to either a standalone directory or a
> >>>> generic component like common or base
> >>>> - As much as possible, documentation files are small and focused on
> >>>> one topic. And then other longer documents are constructed from these
> >>>> snippets of documentation.
> >>>> - We publish to all formats including PDF for users, or HTML for
> >>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
> >>>> help system, instead it just renders generated HTML.
> >>>>
> >>>> As I've worked extensively with Asciidoc I find it easy to pickup
> >>>> (like markdown) but also modular (like docbook and dita). It's also
> >>>> neat that you can sprinkle variables all around in your document so
> >>>> that update is no longer a painful grepping process.
> >>>>
> >>>> Would love to hear your thoughts on this.
> >>>>
> >>>> Cheers,
> >>>>
> >>>> Taher Alkhateeb
> 
> 

Re: [Discussion] documentation framework for OFBiz

[Craig Parker <cr...@fossfolks.com>]

I think the doc structure ought to mirror the menu in the software, or 
are you talking about how a doc itself is laid out?


On 01/17/2018 09:25 AM, Sharan Foga wrote:
> Hi Taher
>
> Great work! I tried it out and found it simple and easy to use (and write!). When can we start writing ? :-)
>
> I was thinking to start with basic descriptions of each of the applications, then see how it evolves from there. We can maybe recover some documentation content from various sources including our existing online help system and the wiki.
>
> The documentation structure will maybe need some thought, and we may need to sort out some common template or guidelines around it.
>
> Thanks
> Sharan
>
> On 2018-01-14 12:33, "Sharan Foga"<sh...@apache.org> wrote:
>> Excellent news Taher!
>>
>> Thanks very much for your effort on this. I'll aim to try it out this week and come back with any feedback.
>>
>> Thanks
>> Sharan
>>
>> On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com> wrote:
>>> Hello everyone,
>>>
>>> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
>>> have a small patch in [1] that provides the PoC for integrating
>>> asciidoctor with OFBiz. I also provided in the the JIRA [1]
>>> instructions on how to run it. Essentially, this allows you to create
>>> documentation for any component by simply creating a src/docs/asciidoc
>>> directory and putting files inside.
>>>
>>> This solution is flexible and allows us to build bigger designs on top
>>> of it. Please review it and tell me if you like the general design.
>>>
>>> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
>>>
>>> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
>>> <sl...@gmail.com> wrote:
>>>> Hello Folks,
>>>>
>>>> We've had this discussion multiple times in the past, but I think I
>>>> have a more concrete idea this time for solving this problem. In the
>>>> past few weeks we've been working internally in Pythys to figure out
>>>> the best way to write and distribute documentation, and I think most
>>>> of that is applicable to OFBiz.
>>>>
>>>> In a nutshell, here is the idea (practically) for how to proceed:
>>>>
>>>> - The documentation language to use is Asciidoc
>>>> - The documentation tool is Asciidoctor
>>>> - Publishing happens through Gradle using the asciidoctor gradle
>>>> plugin (not the OFBiz framework or anything else).
>>>> - The only place where we write documentation is inside the code base
>>>> - Every component contains its own documentation
>>>> - General documentation goes to either a standalone directory or a
>>>> generic component like common or base
>>>> - As much as possible, documentation files are small and focused on
>>>> one topic. And then other longer documents are constructed from these
>>>> snippets of documentation.
>>>> - We publish to all formats including PDF for users, or HTML for
>>>> embedded help and wiki pages. So OFBiz does not parse docbook for its
>>>> help system, instead it just renders generated HTML.
>>>>
>>>> As I've worked extensively with Asciidoc I find it easy to pickup
>>>> (like markdown) but also modular (like docbook and dita). It's also
>>>> neat that you can sprinkle variables all around in your document so
>>>> that update is no longer a painful grepping process.
>>>>
>>>> Would love to hear your thoughts on this.
>>>>
>>>> Cheers,
>>>>
>>>> Taher Alkhateeb

Re: [Discussion] documentation framework for OFBiz

[Sharan Foga <sh...@apache.org>]

Hi Taher

Great work! I tried it out and found it simple and easy to use (and write!). When can we start writing ? :-)

I was thinking to start with basic descriptions of each of the applications, then see how it evolves from there. We can maybe recover some documentation content from various sources including our existing online help system and the wiki.

The documentation structure will maybe need some thought, and we may need to sort out some common template or guidelines around it.

Thanks
Sharan

On 2018-01-14 12:33, "Sharan Foga"<sh...@apache.org> wrote: 
> Excellent news Taher!
> 
> Thanks very much for your effort on this. I'll aim to try it out this week and come back with any feedback.
> 
> Thanks
> Sharan
> 
> On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com> wrote: 
> > Hello everyone,
> > 
> > Sorry for the delay on my part, I got a little preoccupied. Anyway, I
> > have a small patch in [1] that provides the PoC for integrating
> > asciidoctor with OFBiz. I also provided in the the JIRA [1]
> > instructions on how to run it. Essentially, this allows you to create
> > documentation for any component by simply creating a src/docs/asciidoc
> > directory and putting files inside.
> > 
> > This solution is flexible and allows us to build bigger designs on top
> > of it. Please review it and tell me if you like the general design.
> > 
> > [1] https://issues.apache.org/jira/browse/OFBIZ-9873
> > 
> > On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
> > <sl...@gmail.com> wrote:
> > > Hello Folks,
> > >
> > > We've had this discussion multiple times in the past, but I think I
> > > have a more concrete idea this time for solving this problem. In the
> > > past few weeks we've been working internally in Pythys to figure out
> > > the best way to write and distribute documentation, and I think most
> > > of that is applicable to OFBiz.
> > >
> > > In a nutshell, here is the idea (practically) for how to proceed:
> > >
> > > - The documentation language to use is Asciidoc
> > > - The documentation tool is Asciidoctor
> > > - Publishing happens through Gradle using the asciidoctor gradle
> > > plugin (not the OFBiz framework or anything else).
> > > - The only place where we write documentation is inside the code base
> > > - Every component contains its own documentation
> > > - General documentation goes to either a standalone directory or a
> > > generic component like common or base
> > > - As much as possible, documentation files are small and focused on
> > > one topic. And then other longer documents are constructed from these
> > > snippets of documentation.
> > > - We publish to all formats including PDF for users, or HTML for
> > > embedded help and wiki pages. So OFBiz does not parse docbook for its
> > > help system, instead it just renders generated HTML.
> > >
> > > As I've worked extensively with Asciidoc I find it easy to pickup
> > > (like markdown) but also modular (like docbook and dita). It's also
> > > neat that you can sprinkle variables all around in your document so
> > > that update is no longer a painful grepping process.
> > >
> > > Would love to hear your thoughts on this.
> > >
> > > Cheers,
> > >
> > > Taher Alkhateeb
> > 
> 

Re: [Discussion] documentation framework for OFBiz

[Sharan Foga <sh...@apache.org>]

Excellent news Taher!

Thanks very much for your effort on this. I'll aim to try it out this week and come back with any feedback.

Thanks
Sharan

On 2018-01-12 17:36, Taher Alkhateeb <sl...@gmail.com> wrote: 
> Hello everyone,
> 
> Sorry for the delay on my part, I got a little preoccupied. Anyway, I
> have a small patch in [1] that provides the PoC for integrating
> asciidoctor with OFBiz. I also provided in the the JIRA [1]
> instructions on how to run it. Essentially, this allows you to create
> documentation for any component by simply creating a src/docs/asciidoc
> directory and putting files inside.
> 
> This solution is flexible and allows us to build bigger designs on top
> of it. Please review it and tell me if you like the general design.
> 
> [1] https://issues.apache.org/jira/browse/OFBIZ-9873
> 
> On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
> <sl...@gmail.com> wrote:
> > Hello Folks,
> >
> > We've had this discussion multiple times in the past, but I think I
> > have a more concrete idea this time for solving this problem. In the
> > past few weeks we've been working internally in Pythys to figure out
> > the best way to write and distribute documentation, and I think most
> > of that is applicable to OFBiz.
> >
> > In a nutshell, here is the idea (practically) for how to proceed:
> >
> > - The documentation language to use is Asciidoc
> > - The documentation tool is Asciidoctor
> > - Publishing happens through Gradle using the asciidoctor gradle
> > plugin (not the OFBiz framework or anything else).
> > - The only place where we write documentation is inside the code base
> > - Every component contains its own documentation
> > - General documentation goes to either a standalone directory or a
> > generic component like common or base
> > - As much as possible, documentation files are small and focused on
> > one topic. And then other longer documents are constructed from these
> > snippets of documentation.
> > - We publish to all formats including PDF for users, or HTML for
> > embedded help and wiki pages. So OFBiz does not parse docbook for its
> > help system, instead it just renders generated HTML.
> >
> > As I've worked extensively with Asciidoc I find it easy to pickup
> > (like markdown) but also modular (like docbook and dita). It's also
> > neat that you can sprinkle variables all around in your document so
> > that update is no longer a painful grepping process.
> >
> > Would love to hear your thoughts on this.
> >
> > Cheers,
> >
> > Taher Alkhateeb
> 

Re: [Discussion] documentation framework for OFBiz

[Taher Alkhateeb <sl...@gmail.com>]

Hello everyone,

Sorry for the delay on my part, I got a little preoccupied. Anyway, I
have a small patch in [1] that provides the PoC for integrating
asciidoctor with OFBiz. I also provided in the the JIRA [1]
instructions on how to run it. Essentially, this allows you to create
documentation for any component by simply creating a src/docs/asciidoc
directory and putting files inside.

This solution is flexible and allows us to build bigger designs on top
of it. Please review it and tell me if you like the general design.

[1] https://issues.apache.org/jira/browse/OFBIZ-9873

On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
<sl...@gmail.com> wrote:
> Hello Folks,
>
> We've had this discussion multiple times in the past, but I think I
> have a more concrete idea this time for solving this problem. In the
> past few weeks we've been working internally in Pythys to figure out
> the best way to write and distribute documentation, and I think most
> of that is applicable to OFBiz.
>
> In a nutshell, here is the idea (practically) for how to proceed:
>
> - The documentation language to use is Asciidoc
> - The documentation tool is Asciidoctor
> - Publishing happens through Gradle using the asciidoctor gradle
> plugin (not the OFBiz framework or anything else).
> - The only place where we write documentation is inside the code base
> - Every component contains its own documentation
> - General documentation goes to either a standalone directory or a
> generic component like common or base
> - As much as possible, documentation files are small and focused on
> one topic. And then other longer documents are constructed from these
> snippets of documentation.
> - We publish to all formats including PDF for users, or HTML for
> embedded help and wiki pages. So OFBiz does not parse docbook for its
> help system, instead it just renders generated HTML.
>
> As I've worked extensively with Asciidoc I find it easy to pickup
> (like markdown) but also modular (like docbook and dita). It's also
> neat that you can sprinkle variables all around in your document so
> that update is no longer a painful grepping process.
>
> Would love to hear your thoughts on this.
>
> Cheers,
>
> Taher Alkhateeb