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 <michael.br...@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 <michael.br...@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 <sha...@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 <slidingfilame...@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" <michael.br...@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 >>>>>>>> <michael.br...@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 >>>>>>>>> >>>>>>>>> >>>> >>> > >
