OFBiz › OFBiz - Dev

OFBIZ-4941

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

27 messages Options

Jacopo Cappellato-4

Re: OFBIZ-4941

On Nov 10, 2012, at 8:51 PM, Tom wrote:

> C) All the help was placed in the content component because it was the home
> for a subset of the docbook xls distribution. It made sense to replace that
> code with the latest implementation and keep everything in one place rather
> then do something in special purpose or hot deploy with a duplicate xls
> code. It also makes sense since help is content and not an application. I do
> not see how moving the content to the application will make it independent.
> Are you going to duplicate the docbook distribution in each application?

I am talking about the content of help pages for the applications, this should go out of the "content" component (imo it should be an hot-deploy component that can be added to add help pages at runtime).

Jacopo

Jacques Le Roux

Re: OFBIZ-4941

Administrator

From: "Jacopo Cappellato" <[hidden email]>

> On Nov 10, 2012, at 8:51 PM, Tom wrote:
>
>> C) All the help was placed in the content component because it was the home
>> for a subset of the docbook xls distribution. It made sense to replace that
>> code with the latest implementation and keep everything in one place rather
>> then do something in special purpose or hot deploy with a duplicate xls
>> code. It also makes sense since help is content and not an application. I do
>> not see how moving the content to the application will make it independent.
>> Are you going to duplicate the docbook distribution in each application?
>
> I am talking about the content of help pages for the applications, this should go out of the "content" component (imo it should be an hot-deploy component that can be added to add help pages at runtime).
>
> Jacopo

I'm most inclidned to Anil's proposition in Jira https://issues.apache.org/jira/browse/OFBIZ-4941?focusedCommentId=13494790&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13494790
Abstract:
New specialpurpose (to keep OOTB) help component with Docbook inside. I don't think we need any of content component, Tom?

With this new help component it's more logical to keep in the content of current applications\content\data\helpdata\docbookhelp.

So it seems to be "just" about moving
1.
applications\content\data\helpdata\docbookhelp
and
applications\content\template\docbook

2. Adapt the build script (not sure much is needed)
applications/content/template/docbook/webhelp/build.properties
applications/content/template/docbook/webhelp/build.xml
What's more Tom?

License:
Jacopo, as I said, I already checked the license https://issues.apache.org/jira/browse/OFBIZ-4941?focusedCommentId=13471175&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13471175
So we will only to add a line in LICENSE for
current applications/content/template/docbook/webhelp/*
and a section in NOTICE with the speficic
<<Any stylesheet derived from this Software that is publicly distributed will be identified with a different name and the version strings in any derived Software will be changed so that no possibility of confusion between the derived package and this Software will exist.>>
Tom, I have also changed the content of template/docbook/webhelp/LICENSE to
<<See template/docbook/webhelp/docs/content/index.html>> to make things more obvious, to be adapted when moved maybe.

It seems we are near an agreement with as mich as possible changes for Tom :)

Jacques

Jacques Le Roux

Re: OFBIZ-4941

Administrator

FYI: I have attached a new patch with few changes in
LICENSE
NOTICE
applications/content/template/docbook/webhelp/LICENSE

at https://issues.apache.org/jira/browse/OFBIZ-4941

Jacques

From: "Jacques Le Roux" <[hidden email]>

> From: "Jacopo Cappellato" <[hidden email]>
>> On Nov 10, 2012, at 8:51 PM, Tom wrote:
>>
>>> C) All the help was placed in the content component because it was the home
>>> for a subset of the docbook xls distribution. It made sense to replace that
>>> code with the latest implementation and keep everything in one place rather
>>> then do something in special purpose or hot deploy with a duplicate xls
>>> code. It also makes sense since help is content and not an application. I do
>>> not see how moving the content to the application will make it independent.
>>> Are you going to duplicate the docbook distribution in each application?
>>
>> I am talking about the content of help pages for the applications, this should go out of the "content" component (imo it should be an hot-deploy component that can be added to add help pages at runtime).
>>
>> Jacopo
>
> I'm most inclidned to Anil's proposition in Jira https://issues.apache.org/jira/browse/OFBIZ-4941?focusedCommentId=13494790&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13494790
> Abstract:
> New specialpurpose (to keep OOTB) help component with Docbook inside. I don't think we need any of content component, Tom?
>
> With this new help component it's more logical to keep in the content of current applications\content\data\helpdata\docbookhelp.
>
> So it seems to be "just" about moving
> 1.
> applications\content\data\helpdata\docbookhelp
> and
> applications\content\template\docbook
>
> 2. Adapt the build script (not sure much is needed)
> applications/content/template/docbook/webhelp/build.properties
> applications/content/template/docbook/webhelp/build.xml
> What's more Tom?
>
> License:
> Jacopo, as I said, I already checked the license https://issues.apache.org/jira/browse/OFBIZ-4941?focusedCommentId=13471175&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13471175
> So we will only to add a line in LICENSE for
> current applications/content/template/docbook/webhelp/*
> and a section in NOTICE with the speficic
> <<Any stylesheet derived from this Software that is publicly distributed will be identified with a different name and the version strings in any derived Software will be changed so that no possibility of confusion between the derived package and this Software will exist.>>
> Tom, I have also changed the content of template/docbook/webhelp/LICENSE to
> <<See template/docbook/webhelp/docs/content/index.html>> to make things more obvious, to be adapted when moved maybe.
>
> It seems we are near an agreement with as mich as possible changes for Tom :)
>
> Jacques
>

Tom

Re: OFBIZ-4941

I apologize for the going on at length here but...

The first proposal in 4941 was to use Java Help and the POC
was in hot deploy so content manager was not the first choice for deployment.
Content manager became the home for the solution through this line of thinking.
1. DocBook is the preferred format for OFBiz help.
2. The current system did not provide good support for
DocBook transformation.
3. DocBook xsl is the standard for DocBook transformations.
4. The license friendly webhelp component is a good solution
for providing context sensitive help for OFBiz using DocBook xsl.
5. DocBook xsl was already in the OFBiz content component but
did not have the webhelp component.
6. There was no compelling reason to create a new component
for help and have duplicate instances of DocBook xsl. Also the assumption is
that DocBook xsl was being used by the content component and so backward
compatibility needed to be considered.
7. DocBook xsl is complex. The path of least resistance was
to extend the example webhelp inside the webhelp component folder. From that it
followed to host the docbook and image files within the content component.

I do not have a clear idea of what is being proposed as an
alternative deployment or why. The move however would be, as Jacques describes,
relatively simple. If you have a suggestion for an alternate deployment please
provide some additional design details.

There appears to be a requirement for developers to override
the current help for a custom implementation. All you need to do for that is
edit or replace the content in the folders in component://content/data/helpdata/docbookhelp
and re-run the ant task for the component. This is done only one time and can
be performed while ofbiz is running.

If there is a requirement to keep your help documents in
your hot deployed application (separate from the content component) we could
extend the create-component ant task to add structure and build logic to
support webhelp. I think if that is the requirement it should be an improvement
in a separate Jira issue. In my mind it would be a lower priority then working
on improving the quality of the content in the help documents.

One last note (we all hope). Currently the solution does not
use the content management system however I can see adding the docbook
documents under docbookhelp as resources and having the content entity drive PDF
output using fop and the docbook fo. I think that using the resources of the
DocBook xsl in content manager is a good argument for leaving it where it is.

Again, I apologize for the length of these posts.

Tom

________________________________
From: Jacques Le Roux <[hidden email]>
To: [hidden email]
Sent: Sunday, November 11, 2012 3:22 AM
Subject: Re: OFBIZ-4941

FYI: I have attached a new patch with few changes in
LICENSE
NOTICE
applications/content/template/docbook/webhelp/LICENSE

at https://issues.apache.org/jira/browse/OFBIZ-4941

Jacques

From: "Jacques Le Roux" <[hidden email]>

Jacques Le Roux

Re: OFBIZ-4941

Administrator

Thanks Tom,

You don't have to apologize, this is a great post which explains/clarifies the situation.

To summarize/rephrase (to be sure I understood Tom's explanations):

Some committers would prefer to have a new specialpurpose help component instead of embedding in content. The idea is to prevent dependencies of the content component on other applications (or even framework) components.
This is a late requirement from Tom's perspective, since Docbook is already in the content component, and Webhelp is (a new) part of Docbook.
Also keeping Docbook in the content component could have some interested. Notably to use content management for help data.

Actually there are 2 different things. We theoritically can keep Webhelp in content under Docbook (its right place) and have a help component for the help data themselves. But from point 7 below this would need (much, Tom?) more work.
If ever we go this way, we need a clear design before changing things again...!

Overriding in hot-deploy is not an issue either in content or (new) help component, but would need more work (to extend create-component target)

Last but not least, if I have well understood, Tom used the previous help data to (partially for now) build the new help. The new help (will totally) replace/s the old data and have no dependencies on them.
BTW Tom: all the xml files under applications\content\data\helpdata\docbookhelp miss the ASL2 header...

Jacques

Tom Burns wrote:

> I apologize for the going on at length here but...
>
> The first proposal in 4941 was to use Java Help and the POC
> was in hot deploy so content manager was not the first choice for deployment.
> Content manager became the home for the solution through this line of thinking.
> 1. DocBook is the preferred format for OFBiz help.
> 2. The current system did not provide good support for
> DocBook transformation.
> 3. DocBook xsl is the standard for DocBook transformations.
> 4. The license friendly webhelp component is a good solution
> for providing context sensitive help for OFBiz using DocBook xsl.
> 5. DocBook xsl was already in the OFBiz content component but
> did not have the webhelp component.
> 6. There was no compelling reason to create a new component
> for help and have duplicate instances of DocBook xsl. Also the assumption is
> that DocBook xsl was being used by the content component and so backward
> compatibility needed to be considered.
> 7. DocBook xsl is complex. The path of least resistance was
> to extend the example webhelp inside the webhelp component folder. From that it
> followed to host the docbook and image files within the content component.
>
> I do not have a clear idea of what is being proposed as an
> alternative deployment or why. The move however would be, as Jacques describes,
> relatively simple. If you have a suggestion for an alternate deployment please
> provide some additional design details.
>
>
> There appears to be a requirement for developers to override
> the current help for a custom implementation. All you need to do for that is
> edit or replace the content in the folders in component://content/data/helpdata/docbookhelp
> and re-run the ant task for the component. This is done only one time and can
> be performed while ofbiz is running.
>
> If there is a requirement to keep your help documents in
> your hot deployed application (separate from the content component) we could
> extend the create-component ant task to add structure and build logic to
> support webhelp. I think if that is the requirement it should be an improvement
> in a separate Jira issue. In my mind it would be a lower priority then working
> on improving the quality of the content in the help documents.
>
> One last note (we all hope). Currently the solution does not
> use the content management system however I can see adding the docbook
> documents under docbookhelp as resources and having the content entity drive PDF
> output using fop and the docbook fo. I think that using the resources of the
> DocBook xsl in content manager is a good argument for leaving it where it is.
>
> Again, I apologize for the length of these posts.
>
> Tom
>
>
>
>
> ________________________________
> From: Jacques Le Roux <[hidden email]>
> To: [hidden email]
> Sent: Sunday, November 11, 2012 3:22 AM
> Subject: Re: OFBIZ-4941
>
> FYI: I have attached a new patch with few changes in
> LICENSE
> NOTICE
> applications/content/template/docbook/webhelp/LICENSE
>
> at https://issues.apache.org/jira/browse/OFBIZ-4941
>
> Jacques
>
> From: "Jacques Le Roux" <[hidden email]>
>> From: "Jacopo Cappellato" <[hidden email]>
>>> On Nov 10, 2012, at 8:51 PM, Tom wrote:
>>>
>>>> C) All the help was placed in the content component because it was the home
>>>> for a subset of the docbook xls distribution. It made sense to replace that
>>>> code with the latest implementation and keep everything in one place rather
>>>> then do something in special purpose or hot deploy with a duplicate xls
>>>> code. It also makes sense since help is content and not an application. I do
>>>> not see how moving the content to the application will make it independent.
>>>> Are you going to duplicate the docbook distribution in each application?
>>>
>>> I am talking about the content of help pages for the applications, this should go out of the "content" component (imo it should
>>> be an hot-deploy component that can be added to add help pages at runtime).
>>>
>>> Jacopo
>>
>> I'm most inclidned to Anil's proposition in Jira
>> https://issues.apache.org/jira/browse/OFBIZ-4941?focusedCommentId=13494790&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13494790
>> Abstract:
>> New specialpurpose (to keep OOTB) help component with Docbook inside. I don't think we need any of content component, Tom?
>>
>> With this new help component it's more logical to keep in the content of current applications\content\data\helpdata\docbookhelp.
>>
>> So it seems to be "just" about moving
>> 1.
>> applications\content\data\helpdata\docbookhelp
>> and
>> applications\content\template\docbook
>>
>> 2. Adapt the build script (not sure much is needed)
>> applications/content/template/docbook/webhelp/build.properties
>> applications/content/template/docbook/webhelp/build.xml
>> What's more Tom?
>>
>> License:
>> Jacopo, as I said, I already checked the license
>> https://issues.apache.org/jira/browse/OFBIZ-4941?focusedCommentId=13471175&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13471175
>> So we will only to add a line in LICENSE for
>> current applications/content/template/docbook/webhelp/*
>> and a section in NOTICE with the speficic
>> <<Any stylesheet derived from this Software that is publicly distributed will be identified with a different name and the
>> version strings in any derived Software will be changed so that no possibility of confusion between the derived package and this
>> Software will exist.>> Tom, I have also changed the content of template/docbook/webhelp/LICENSE to <<See
>> template/docbook/webhelp/docs/content/index.html>> to make things more obvious, to be adapted when moved maybe.
>>
>> It seems we are near an agreement with as mich as possible changes for Tom :)
>>
>> Jacques

Tom

Re: OFBIZ-4941

Jacques,

I think that's about it. Re 7 I would like to keep everything together.

I assume you will take care of the ASL2 headers.

By the way there appears to be a defect in the CMS web site in the content component.

https://demo-stable.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_PDF is delivering un-formatted text in a file with an html type (the link promises a PDF file). Could be a browser thing but I don't think so.

The content manager dataresource Object Info is "applications/content/template/docbook/fo/docbook.xsl". This problem preceded the update to the docbook folder.

I'm not sure how the link in Object Info is used in transformation by the CMS web app. If we get it working we could add the help docbook files to the CMS to demonstrate alternate help deployments like http://fusesource.com/products/fuse-esb-enterprise/#documentation.

Can you confirm the problem (not a browser problem) and I will open a defect in jira.

Thanks,

Tom

________________________________
From: Jacques Le Roux <[hidden email]>
To: [hidden email]; Tom Burns <[hidden email]>
Sent: Sunday, November 11, 2012 11:30 AM
Subject: Re: OFBIZ-4941

Thanks Tom,

You don't have to apologize, this is a great post which explains/clarifies the situation.

To summarize/rephrase (to be sure I understood Tom's explanations):

Some committers would prefer to have a new specialpurpose help component instead of embedding in content. The idea is to prevent dependencies of the content component on other applications (or even framework) components.
This is a late requirement from Tom's perspective, since Docbook is already in the content component, and Webhelp is (a new) part of Docbook.
Also keeping Docbook in the content component could have some interested. Notably to use content management for help data.

Actually there are 2 different things. We theoritically can keep Webhelp in content under Docbook (its right place) and have a help component for the help data themselves. But from point 7 below this would need (much, Tom?) more work.
If ever we go this way, we need a clear design before changing things again...!

Overriding in hot-deploy is not an issue either in content or (new) help component, but would need more work (to extend create-component target)

Last but not least, if I have well understood, Tom used the previous help data to (partially for now) build the new help. The new help (will totally) replace/s the old data and have no dependencies on them.
BTW Tom: all the xml files under applications\content\data\helpdata\docbookhelp miss the ASL2 header...

Jacques

Tom Burns wrote:

Jacques Le Roux

Re: OFBIZ-4941

Administrator

Tom Burns wrote:
> Jacques,
>
> I think that's about it. Re 7 I would like to keep everything together.
>
> I assume you will take care of the ASL2 headers.

Yes, no pb.

>
> By the way there appears to be a defect in the CMS web site in the content component.
>
> https://demo-stable.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_PDF is delivering un-formatted text in a file with an html type
> (the link promises a PDF file). Could be a browser thing but I don't think so.

I reproduce in those browsers (FF, Chrome, Opera), curiously IE8 does not respond

Jacques

>
> The content manager dataresource Object Info is "applications/content/template/docbook/fo/docbook.xsl". This problem preceded the
> update to the docbook folder.
>
> I'm not sure how the link in Object Info is used in transformation by the CMS web app. If we get it working we could add the help
> docbook files to the CMS to demonstrate alternate help deployments like
> http://fusesource.com/products/fuse-esb-enterprise/#documentation.
>
>
> Can you confirm the problem (not a browser problem) and I will open a defect in jira.
>
> Thanks,
>
> Tom
>
>
>
>
> ________________________________
> From: Jacques Le Roux <[hidden email]>
> To: [hidden email]; Tom Burns <[hidden email]>
> Sent: Sunday, November 11, 2012 11:30 AM
> Subject: Re: OFBIZ-4941
>
> Thanks Tom,
>
> You don't have to apologize, this is a great post which explains/clarifies the situation.
>
> To summarize/rephrase (to be sure I understood Tom's explanations):
>
> Some committers would prefer to have a new specialpurpose help component instead of embedding in content. The idea is to prevent
> dependencies of the content component on other applications (or even framework) components.
> This is a late requirement from Tom's perspective, since Docbook is already in the content component, and Webhelp is (a new) part
> of Docbook.
> Also keeping Docbook in the content component could have some interested. Notably to use content management for help data.
>
> Actually there are 2 different things. We theoritically can keep Webhelp in content under Docbook (its right place) and have a
> help component for the help data themselves. But from point 7 below this would need (much, Tom?) more work.
> If ever we go this way, we need a clear design before changing things again...!
>
> Overriding in hot-deploy is not an issue either in content or (new) help component, but would need more work (to extend
> create-component target)
>
> Last but not least, if I have well understood, Tom used the previous help data to (partially for now) build the new help. The new
> help (will totally) replace/s the old data and have no dependencies on them.
> BTW Tom: all the xml files under applications\content\data\helpdata\docbookhelp miss the ASL2 header...
>
> Jacques
>
> Tom Burns wrote:
>> I apologize for the going on at length here but...
>>
>> The first proposal in 4941 was to use Java Help and the POC
>> was in hot deploy so content manager was not the first choice for deployment.
>> Content manager became the home for the solution through this line of thinking.
>> 1. DocBook is the preferred format for OFBiz help.
>> 2. The current system did not provide good support for
>> DocBook transformation.
>> 3. DocBook xsl is the standard for DocBook transformations.
>> 4. The license friendly webhelp component is a good solution
>> for providing context sensitive help for OFBiz using DocBook xsl.
>> 5. DocBook xsl was already in the OFBiz content component but
>> did not have the webhelp component.
>> 6. There was no compelling reason to create a new component
>> for help and have duplicate instances of DocBook xsl. Also the assumption is
>> that DocBook xsl was being used by the content component and so backward
>> compatibility needed to be considered.
>> 7. DocBook xsl is complex. The path of least resistance was
>> to extend the example webhelp inside the webhelp component folder. From that it
>> followed to host the docbook and image files within the content component.
>>
>> I do not have a clear idea of what is being proposed as an
>> alternative deployment or why. The move however would be, as Jacques describes,
>> relatively simple. If you have a suggestion for an alternate deployment please
>> provide some additional design details.
>>
>>
>> There appears to be a requirement for developers to override
>> the current help for a custom implementation. All you need to do for that is
>> edit or replace the content in the folders in component://content/data/helpdata/docbookhelp
>> and re-run the ant task for the component. This is done only one time and can
>> be performed while ofbiz is running.
>>
>> If there is a requirement to keep your help documents in
>> your hot deployed application (separate from the content component) we could
>> extend the create-component ant task to add structure and build logic to
>> support webhelp. I think if that is the requirement it should be an improvement
>> in a separate Jira issue. In my mind it would be a lower priority then working
>> on improving the quality of the content in the help documents.
>>
>> One last note (we all hope). Currently the solution does not
>> use the content management system however I can see adding the docbook
>> documents under docbookhelp as resources and having the content entity drive PDF
>> output using fop and the docbook fo. I think that using the resources of the
>> DocBook xsl in content manager is a good argument for leaving it where it is.
>>
>> Again, I apologize for the length of these posts.
>>
>> Tom
>>
>>
>>
>>
>> ________________________________
>> From: Jacques Le Roux <[hidden email]>
>> To: [hidden email]
>> Sent: Sunday, November 11, 2012 3:22 AM
>> Subject: Re: OFBIZ-4941
>>
>> FYI: I have attached a new patch with few changes in
>> LICENSE
>> NOTICE
>> applications/content/template/docbook/webhelp/LICENSE
>>
>> at https://issues.apache.org/jira/browse/OFBIZ-4941
>>
>> Jacques
>>
>> From: "Jacques Le Roux" <[hidden email]>
>>> From: "Jacopo Cappellato" <[hidden email]>
>>>> On Nov 10, 2012, at 8:51 PM, Tom wrote:
>>>>
>>>>> C) All the help was placed in the content component because it was the home
>>>>> for a subset of the docbook xls distribution. It made sense to replace that
>>>>> code with the latest implementation and keep everything in one place rather
>>>>> then do something in special purpose or hot deploy with a duplicate xls
>>>>> code. It also makes sense since help is content and not an application. I do
>>>>> not see how moving the content to the application will make it independent.
>>>>> Are you going to duplicate the docbook distribution in each application?
>>>>
>>>> I am talking about the content of help pages for the applications, this should go out of the "content" component (imo it should
>>>> be an hot-deploy component that can be added to add help pages at runtime).
>>>>
>>>> Jacopo
>>>
>>> I'm most inclidned to Anil's proposition in Jira
>>> https://issues.apache.org/jira/browse/OFBIZ-4941?focusedCommentId=13494790&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13494790
>>> Abstract:
>>> New specialpurpose (to keep OOTB) help component with Docbook inside. I don't think we need any of content component, Tom?
>>>
>>> With this new help component it's more logical to keep in the content of current applications\content\data\helpdata\docbookhelp.
>>>
>>> So it seems to be "just" about moving
>>> 1.
>>> applications\content\data\helpdata\docbookhelp
>>> and
>>> applications\content\template\docbook
>>>
>>> 2. Adapt the build script (not sure much is needed)
>>> applications/content/template/docbook/webhelp/build.properties
>>> applications/content/template/docbook/webhelp/build.xml
>>> What's more Tom?
>>>
>>> License:
>>> Jacopo, as I said, I already checked the license
>>> https://issues.apache.org/jira/browse/OFBIZ-4941?focusedCommentId=13471175&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13471175
>>> So we will only to add a line in LICENSE for
>>> current applications/content/template/docbook/webhelp/*
>>> and a section in NOTICE with the speficic
>>> <<Any stylesheet derived from this Software that is publicly distributed will be identified with a different name and the
>>> version strings in any derived Software will be changed so that no possibility of confusion between the derived package and this
>>> Software will exist.>> Tom, I have also changed the content of template/docbook/webhelp/LICENSE to <<See
>>> template/docbook/webhelp/docs/content/index.html>> to make things more obvious, to be adapted when moved maybe.
>>>
>>> It seems we are near an agreement with as mich as possible changes for Tom :)
>>>
>>> Jacques