ofbiz-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jacques Le Roux <jacques.le.r...@les7arts.com>
Subject Re: OFBiz Documentation Team Volunteers Needed
Date Sat, 10 Feb 2018 10:21:54 GMT
Hi Olivier,

I read at https://github.com/asciidoctor/docbookrx that
"This converter is far from perfect at the moment and some of the conversion is done hastily.
The plan is to evolve it into a robust library for 
performing this conversion in a reliable way."

The last version of Pandoc (2.1.1) supports conversion from docbook to asciido. I have tried
it but it seems not all is supported for instance using 
HELP_ACCOUNTING_agreements.xml (picked by chance)
     pandoc -f docbook -t asciidoc HELP_ACCOUNTING_agreements.xml -o test.txt
in
     applications\accounting\data\helpdata

I get this:
<<
Agreements.
-----------

An agreement is a way of recording a business arrangements or contract
that your business makes with other companies or individuals. Common
examples include Payment Terms (where you allow a customer up to 30 days
to pay you) or Prompt Payment Discounts (where you offer a reduction on
the amount owing if your customer pays you before a certain date)

It can be used for the following:

* Defining Payment Terms for Customers or Suppliers
* Defining Sales Commissions
* Setting up Prompt Payment Discounts
* Setting up Price Lists (NOTE TO DO: Need to investigate how this logic
overlaps with PRICE RULES in Catalog Manager)
* Defining Late Fee Penalties
* Defining preferred freight carriers or specific codes to be used
 >>

At 1st glance the text is limited in width to something like 72 chars I guess/hope this can
be changed.
And the included/linked documents are not  present.
And yes, asciidoc can link
http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#links
https://github.com/asciidoctor/asciidoctor/wiki/How-to-link-to-a-relative-AsciiDoc-document

Could you please try the same with docbookrx to see if we get something better?

I agree about the importance of the contextual help in its 2 aspects

 1.  From the "?" or "Help" button in UI
 2. as an URL like https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML

We could create a branch to convert all as you suggest and see what is exploitable.

Thanks

Jacques

Le 09/02/2018 à 10:48, Olivier Heintz a écrit :
> good tools are tools which help to work not to (try to) replace human works. :-)
>
> 1) Conversion from docbook to asciidoc will just help us to  work on content and not
on technical syntax.
>
> 2) Current ofbiz help system has some weakness but it works and, as it's easy, to update
data to use it with html file generate from ascii it's a good
> tools to test if some content is usable (or not) in a contextual help.
> But I agree, I don't know when contextual help  will be in the task list of the Documentation
team ;-)
>
> Olivier
>
> Le 08/02/2018 à 14:25, Michael Brohl a écrit :
>> +++1 for manually reviewing, updating, restructuring and enhancing the
>> documentation instead of copy & paste!
>>
>> We know that the documentation has very different quality, is sometimes
>> outdated or too brief etc.
>>
>> I think it is of more value to take the chance to make the documentation
>> itself better in the course of the migration instead of simply having
>> the old state in a new format.
>>
>> We should maybe also agree on writing new documentation (or anhancing a
>> good amount of documentation) directly in the new format instead of
>> putting it in confluence 8if applicable)?
>>
>> Thanks,
>>
>> Michael
>>
>>
>> Am 08.02.18 um 11:33 schrieb Taher Alkhateeb:
>>> It is heartwarming to see you fine people signing up. I am thrilled
>>> and looking forward to working with you. And I have to say Sharan
>>> knows how to bring us together, so thank you!
>>>
>>> In reference to Olivier's comment regarding using conversion tools, I
>>> would advise to perhaps try to be careful. Our objective is not
>>> necessarily to copy-paste existing documentation, but rather to write
>>> clean, relevant and well thought out documentation. If an old piece of
>>> documentation is good and relevant, we use it, if not, we update it
>>> and clean it, or of it is not useful then we just drop it.
>>>
>>> I hope more people feel the urge to sign up. What you folks are going
>>> to achieve is to make OFBiz much more competitive by giving
>>> accessibility to new comers through comprehensive documentation.
>>>
>>> On Thu, Feb 8, 2018 at 1:04 PM, Aditya Sharma
>>> <aditya.sharma@hotwaxsystems.com> wrote:
>>>> Hi Sharan,
>>>>
>>>> Please count me in.
>>>>
>>>> Thanks and Regards,
>>>>
>>>> *Aditya Sharma* | Enterprise Software Engineer
>>>> HotWax Commerce <http://www.hotwax.co/> by HotWax Systems
>>>> <http://www.hotwaxsystems.com/>
>>>>
>>>> <https://www.linkedin.com/in/aditya-sharma-78291810a/>
>>>>
>>>> On Thu, Feb 8, 2018 at 2:25 PM, Olivier Heintz <
>>>> holivier.lists@ofbizextra.org> wrote:
>>>>
>>>>> Hi Sharan,
>>>>>
>>>>> please add me to the list,
>>>>>
>>>>> I have start to play with the new tools
>>>>> I have convert some docbook file to asciidoc with docbookrx tools and
make
>>>>> modification on help data to use the html generated files in the ofbiz
>>>>> help, it's work's ;-)
>>>>> If needed, I can convert all docbook files to asccidoc
>>>>>
>>>>>
>>>>> Regards,
>>>>>
>>>>>
>>>>>
>>>>> Le 07/02/2018 à 14:32, Sharan Foga a écrit :
>>>>>> Hi Everyone
>>>>>>
>>>>>> (Trying again as my first post didn't reach this list)
>>>>>>
>>>>>> If you have read the latest project blog post then you will have
seen a
>>>>> section about the discussions that have been happening on our development
>>>>> list about the new proposed OFBiz documentation framework.
>>>>>> https://s.apache.org/VfxE
>>>>>>
>>>>>> It is based on asciidoc and will be able to generate documentation
in
>>>>> various formats. This means that we can start to consolidate our OFBiz
>>>>> documentation within OFBiz itself and adapt it to any new releases.
>>>>>> Feedback to the proposal have been very positive and once the code
is
>>>>> moved into our current trunk we will need to start some documentation
work.
>>>>> We will be looking for volunteers to become part of a documentation team
>>>>> that will work on reviewing the documents we already have in the wiki
and
>>>>> other sources, then help to re-structure them to fit into the new
>>>>> documentation framework model.
>>>>>> Being involved with documentation is a good way to learn OFBiz :-)
>>>>>>
>>>>>> So if you are interested in being part of the OFBiz documentation
team
>>>>> then please respond to this message and I will add you to the list.
>>>>>> Thanks
>>>>>> Sharan
>>>>>>
>


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message