You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ofbiz.apache.org by Jacques Le Roux <ja...@les7arts.com> on 2020/05/10 16:43:29 UTC
Have a README.TXT file in release package
Hi,
We often get questions from people not reading the basic documentation. Like not able to run Gradle because ignoring init-gradle-wrapper scripts.
I know there will always people not reading the documentation. But maybe, to prevent most obvious questions and tempting RTFM answers, we could add a
small README.TXT with basic information in OFBiz root.
It would ultimately refer to README.adoc. Also saying that README.adoc can be read with a text reader tool. And it's easy to follow
https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
What do you think?
Jacques
Re: Have a README.TXT file in release package
Posted by Jacques Le Roux <ja...@les7arts.com>.
Hi Pierre, All,
I have backported the new INSTALL file in R17 and R18 and closed OFBIZ-11691
Pierre, I suggest you create a Jira for your propositions below. Because moving these scripts has implication in their content (code)
Thanks
Jacques
Le 14/05/2020 à 19:53, Pierre Smits a écrit :
> Indeed.
>
> And while add it, why not just call the two files 'init-gradle'?
>
> Met vriendelijke groet,
>
> Pierre Smits
> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
> 2008 (without privileges)
>
> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> *Apache Directory <https://directory.apache.org>, PMC Member*
> Apache Incubator <https://incubator.apache.org>, committer
> Apache Steve <https://steve.apache.org>, committer
>
>
> On Thu, May 14, 2020 at 7:31 PM Jacques Le Roux <
> jacques.le.roux@les7arts.com> wrote:
>
>> Yes why not put init-gradle-wrapper.sh in main dir? The most simple way :)
>>
>> I know we had this discussion before...
>>
>> Jacques
>>
>> Le 14/05/2020 à 19:04, Pierre Smits a écrit :
>>> Thanks Jacques,
>>>
>>> By the way, why can't both init-gradle-wrapper.sh
>>> <
>> https://github.com/apache/ofbiz-framework/blob/trunk/gradle/init-gradle-wrapper.sh
>>> and init-gradle-wrapper.bat
>>> <
>> https://github.com/apache/ofbiz-framework/blob/trunk/init-gradle-wrapper.bat
>>> be
>>> in the same location? Both do the same thing, but for different OSes
>>>
>>> Met vriendelijke groet,
>>>
>>> Pierre Smits
>>> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
>> since
>>> 2008 (without privileges)
>>>
>>> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
>>> *Apache Directory <https://directory.apache.org>, PMC Member*
>>> Apache Incubator <https://incubator.apache.org>, committer
>>> Apache Steve <https://steve.apache.org>, committer
>>>
>>>
>>> On Thu, May 14, 2020 at 6:51 PM Jacques Le Roux <
>>> jacques.le.roux@les7arts.com> wrote:
>>>
>>>> Hi,
>>>>
>>>> I committed an INSTALL file in trunk main dir, please review and amend
>> if
>>>> necessary
>>>>
>>>> Thanks
>>>>
>>>> Jacques
>>>>
>>>> Le 11/05/2020 à 12:08, Jacques Le Roux a écrit :
>>>>> Thank you All for your answers,
>>>>>
>>>>> I like the idea of creating a simple INSTALL file with minimum
>>>> installation information and redirection to more documentation
>>>>> I created https://issues.apache.org/jira/browse/OFBIZ-11691 for that
>>>>>
>>>>> Jacques
>>>>>
>>>>> Le 10/05/2020 à 18:43, Jacques Le Roux a écrit :
>>>>>> Hi,
>>>>>>
>>>>>> We often get questions from people not reading the basic
>> documentation.
>>>> Like not able to run Gradle because ignoring init-gradle-wrapper
>> scripts.
>>>>>> I know there will always people not reading the documentation. But
>>>> maybe, to prevent most obvious questions and tempting RTFM answers, we
>>>> could add
>>>>>> a small README.TXT with basic information in OFBiz root.
>>>>>>
>>>>>> It would ultimately refer to README.adoc. Also saying that README.adoc
>>>> can be read with a text reader tool. And it's easy to follow
>>>>
>> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
>>>>>> What do you think?
>>>>>>
>>>>>> Jacques
>>>>>>
Re: Have a README.TXT file in release package
Posted by Pierre Smits <pi...@apache.org>.
Indeed.
And while add it, why not just call the two files 'init-gradle'?
Met vriendelijke groet,
Pierre Smits
*Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
2008 (without privileges)
*Apache Trafodion <https://trafodion.apache.org>, Vice President*
*Apache Directory <https://directory.apache.org>, PMC Member*
Apache Incubator <https://incubator.apache.org>, committer
Apache Steve <https://steve.apache.org>, committer
On Thu, May 14, 2020 at 7:31 PM Jacques Le Roux <
jacques.le.roux@les7arts.com> wrote:
> Yes why not put init-gradle-wrapper.sh in main dir? The most simple way :)
>
> I know we had this discussion before...
>
> Jacques
>
> Le 14/05/2020 à 19:04, Pierre Smits a écrit :
> > Thanks Jacques,
> >
> > By the way, why can't both init-gradle-wrapper.sh
> > <
> https://github.com/apache/ofbiz-framework/blob/trunk/gradle/init-gradle-wrapper.sh
> >
> > and init-gradle-wrapper.bat
> > <
> https://github.com/apache/ofbiz-framework/blob/trunk/init-gradle-wrapper.bat
> >
> > be
> > in the same location? Both do the same thing, but for different OSes
> >
> > Met vriendelijke groet,
> >
> > Pierre Smits
> > *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
> since
> > 2008 (without privileges)
> >
> > *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> > *Apache Directory <https://directory.apache.org>, PMC Member*
> > Apache Incubator <https://incubator.apache.org>, committer
> > Apache Steve <https://steve.apache.org>, committer
> >
> >
> > On Thu, May 14, 2020 at 6:51 PM Jacques Le Roux <
> > jacques.le.roux@les7arts.com> wrote:
> >
> >> Hi,
> >>
> >> I committed an INSTALL file in trunk main dir, please review and amend
> if
> >> necessary
> >>
> >> Thanks
> >>
> >> Jacques
> >>
> >> Le 11/05/2020 à 12:08, Jacques Le Roux a écrit :
> >>> Thank you All for your answers,
> >>>
> >>> I like the idea of creating a simple INSTALL file with minimum
> >> installation information and redirection to more documentation
> >>> I created https://issues.apache.org/jira/browse/OFBIZ-11691 for that
> >>>
> >>> Jacques
> >>>
> >>> Le 10/05/2020 à 18:43, Jacques Le Roux a écrit :
> >>>> Hi,
> >>>>
> >>>> We often get questions from people not reading the basic
> documentation.
> >> Like not able to run Gradle because ignoring init-gradle-wrapper
> scripts.
> >>>> I know there will always people not reading the documentation. But
> >> maybe, to prevent most obvious questions and tempting RTFM answers, we
> >> could add
> >>>> a small README.TXT with basic information in OFBiz root.
> >>>>
> >>>> It would ultimately refer to README.adoc. Also saying that README.adoc
> >> can be read with a text reader tool. And it's easy to follow
> >>
> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
> >>>> What do you think?
> >>>>
> >>>> Jacques
> >>>>
>
Re: Have a README.TXT file in release package
Posted by Jacques Le Roux <ja...@les7arts.com>.
Yes why not put init-gradle-wrapper.sh in main dir? The most simple way :)
I know we had this discussion before...
Jacques
Le 14/05/2020 à 19:04, Pierre Smits a écrit :
> Thanks Jacques,
>
> By the way, why can't both init-gradle-wrapper.sh
> <https://github.com/apache/ofbiz-framework/blob/trunk/gradle/init-gradle-wrapper.sh>
> and init-gradle-wrapper.bat
> <https://github.com/apache/ofbiz-framework/blob/trunk/init-gradle-wrapper.bat>
> be
> in the same location? Both do the same thing, but for different OSes
>
> Met vriendelijke groet,
>
> Pierre Smits
> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
> 2008 (without privileges)
>
> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> *Apache Directory <https://directory.apache.org>, PMC Member*
> Apache Incubator <https://incubator.apache.org>, committer
> Apache Steve <https://steve.apache.org>, committer
>
>
> On Thu, May 14, 2020 at 6:51 PM Jacques Le Roux <
> jacques.le.roux@les7arts.com> wrote:
>
>> Hi,
>>
>> I committed an INSTALL file in trunk main dir, please review and amend if
>> necessary
>>
>> Thanks
>>
>> Jacques
>>
>> Le 11/05/2020 à 12:08, Jacques Le Roux a écrit :
>>> Thank you All for your answers,
>>>
>>> I like the idea of creating a simple INSTALL file with minimum
>> installation information and redirection to more documentation
>>> I created https://issues.apache.org/jira/browse/OFBIZ-11691 for that
>>>
>>> Jacques
>>>
>>> Le 10/05/2020 à 18:43, Jacques Le Roux a écrit :
>>>> Hi,
>>>>
>>>> We often get questions from people not reading the basic documentation.
>> Like not able to run Gradle because ignoring init-gradle-wrapper scripts.
>>>> I know there will always people not reading the documentation. But
>> maybe, to prevent most obvious questions and tempting RTFM answers, we
>> could add
>>>> a small README.TXT with basic information in OFBiz root.
>>>>
>>>> It would ultimately refer to README.adoc. Also saying that README.adoc
>> can be read with a text reader tool. And it's easy to follow
>> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
>>>> What do you think?
>>>>
>>>> Jacques
>>>>
Re: Have a README.TXT file in release package
Posted by Pierre Smits <pi...@apache.org>.
Thanks Jacques,
By the way, why can't both init-gradle-wrapper.sh
<https://github.com/apache/ofbiz-framework/blob/trunk/gradle/init-gradle-wrapper.sh>
and init-gradle-wrapper.bat
<https://github.com/apache/ofbiz-framework/blob/trunk/init-gradle-wrapper.bat>
be
in the same location? Both do the same thing, but for different OSes
Met vriendelijke groet,
Pierre Smits
*Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
2008 (without privileges)
*Apache Trafodion <https://trafodion.apache.org>, Vice President*
*Apache Directory <https://directory.apache.org>, PMC Member*
Apache Incubator <https://incubator.apache.org>, committer
Apache Steve <https://steve.apache.org>, committer
On Thu, May 14, 2020 at 6:51 PM Jacques Le Roux <
jacques.le.roux@les7arts.com> wrote:
> Hi,
>
> I committed an INSTALL file in trunk main dir, please review and amend if
> necessary
>
> Thanks
>
> Jacques
>
> Le 11/05/2020 à 12:08, Jacques Le Roux a écrit :
> > Thank you All for your answers,
> >
> > I like the idea of creating a simple INSTALL file with minimum
> installation information and redirection to more documentation
> >
> > I created https://issues.apache.org/jira/browse/OFBIZ-11691 for that
> >
> > Jacques
> >
> > Le 10/05/2020 à 18:43, Jacques Le Roux a écrit :
> >> Hi,
> >>
> >> We often get questions from people not reading the basic documentation.
> Like not able to run Gradle because ignoring init-gradle-wrapper scripts.
> >>
> >> I know there will always people not reading the documentation. But
> maybe, to prevent most obvious questions and tempting RTFM answers, we
> could add
> >> a small README.TXT with basic information in OFBiz root.
> >>
> >> It would ultimately refer to README.adoc. Also saying that README.adoc
> can be read with a text reader tool. And it's easy to follow
> >>
> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
> >>
> >> What do you think?
> >>
> >> Jacques
> >>
>
Re: Have a README.TXT file in release package
Posted by Jacques Le Roux <ja...@les7arts.com>.
Hi,
I committed an INSTALL file in trunk main dir, please review and amend if necessary
Thanks
Jacques
Le 11/05/2020 à 12:08, Jacques Le Roux a écrit :
> Thank you All for your answers,
>
> I like the idea of creating a simple INSTALL file with minimum installation information and redirection to more documentation
>
> I created https://issues.apache.org/jira/browse/OFBIZ-11691 for that
>
> Jacques
>
> Le 10/05/2020 à 18:43, Jacques Le Roux a écrit :
>> Hi,
>>
>> We often get questions from people not reading the basic documentation. Like not able to run Gradle because ignoring init-gradle-wrapper scripts.
>>
>> I know there will always people not reading the documentation. But maybe, to prevent most obvious questions and tempting RTFM answers, we could add
>> a small README.TXT with basic information in OFBiz root.
>>
>> It would ultimately refer to README.adoc. Also saying that README.adoc can be read with a text reader tool. And it's easy to follow
>> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
>>
>> What do you think?
>>
>> Jacques
>>
Re: Have a README.TXT file in release package
Posted by Jacques Le Roux <ja...@les7arts.com>.
Thank you All for your answers,
I like the idea of creating a simple INSTALL file with minimum installation information and redirection to more documentation
I created https://issues.apache.org/jira/browse/OFBIZ-11691 for that
Jacques
Le 10/05/2020 à 18:43, Jacques Le Roux a écrit :
> Hi,
>
> We often get questions from people not reading the basic documentation. Like not able to run Gradle because ignoring init-gradle-wrapper scripts.
>
> I know there will always people not reading the documentation. But maybe, to prevent most obvious questions and tempting RTFM answers, we could add
> a small README.TXT with basic information in OFBiz root.
>
> It would ultimately refer to README.adoc. Also saying that README.adoc can be read with a text reader tool. And it's easy to follow
> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
>
> What do you think?
>
> Jacques
>
Re: Have a README.TXT file in release package
Posted by Pierre Smits <pi...@apache.org>.
Call it INSTALLATION, and simply highlight what is necessary to get OFBiz
running:
Have jdk, version 8
invoke the gradle-init script
I concur with Michael, people who don't read the readme.adoc will possibly
forgo the other readme too.
Met vriendelijke groet,
Pierre Smits
*Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
2008 (without privileges)
*Apache Trafodion <https://trafodion.apache.org>, Vice President*
*Apache Directory <https://directory.apache.org>, PMC Member*
Apache Incubator <https://incubator.apache.org>, committer
Apache Steve <https://steve.apache.org>, committer
On Sun, May 10, 2020 at 7:29 PM Michael Brohl <mi...@ecomify.de>
wrote:
> Hi Jacques,
>
> do you think that people who do not read README.adoc would rather read a
> README.txt file?
>
> I doubt that you'll reach those people with that file but it might be
> worth a try. I would name the file README without extension to better
> match LICENSE, NOTICE, VERSION etc..
>
> Thanks,
>
> Michael Brohl
>
> ecomify GmbH - www.ecomify.de
>
>
> Am 10.05.20 um 18:43 schrieb Jacques Le Roux:
> > Hi,
> >
> > We often get questions from people not reading the basic
> > documentation. Like not able to run Gradle because ignoring
> > init-gradle-wrapper scripts.
> >
> > I know there will always people not reading the documentation. But
> > maybe, to prevent most obvious questions and tempting RTFM answers, we
> > could add a small README.TXT with basic information in OFBiz root.
> >
> > It would ultimately refer to README.adoc. Also saying that README.adoc
> > can be read with a text reader tool. And it's easy to follow
> >
> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
> >
> > What do you think?
> >
> > Jacques
> >
>
>
Re: Have a README.TXT file in release package
Posted by Michael Brohl <mi...@ecomify.de>.
Hi Jacques,
do you think that people who do not read README.adoc would rather read a
README.txt file?
I doubt that you'll reach those people with that file but it might be
worth a try. I would name the file README without extension to better
match LICENSE, NOTICE, VERSION etc..
Thanks,
Michael Brohl
ecomify GmbH - www.ecomify.de
Am 10.05.20 um 18:43 schrieb Jacques Le Roux:
> Hi,
>
> We often get questions from people not reading the basic
> documentation. Like not able to run Gradle because ignoring
> init-gradle-wrapper scripts.
>
> I know there will always people not reading the documentation. But
> maybe, to prevent most obvious questions and tempting RTFM answers, we
> could add a small README.TXT with basic information in OFBiz root.
>
> It would ultimately refer to README.adoc. Also saying that README.adoc
> can be read with a text reader tool. And it's easy to follow
> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
>
> What do you think?
>
> Jacques
>
Re: Have a README.TXT file in release package
Posted by Deepak Nigam <de...@gmail.com>.
+1
Thanks & Regards
--
Deepak Nigam
On Sun, May 10, 2020, 10:15 PM Jacques Le Roux <ja...@les7arts.com>
wrote:
> Hi,
>
> We often get questions from people not reading the basic documentation.
> Like not able to run Gradle because ignoring init-gradle-wrapper scripts.
>
> I know there will always people not reading the documentation. But maybe,
> to prevent most obvious questions and tempting RTFM answers, we could add a
> small README.TXT with basic information in OFBiz root.
>
> It would ultimately refer to README.adoc. Also saying that README.adoc can
> be read with a text reader tool. And it's easy to follow
>
> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
>
> What do you think?
>
> Jacques
>
>
Re: Have a README.TXT file in release package
Posted by Taher Alkhateeb <ta...@pythys.com.INVALID>.
If I see two README files in a project, I would get confused. Conventions are usually that there is only one README, one LICENSE, one INSTALL and so on ...
Perhaps another approach is to slimdown the README file and refer to other documentation using links to the other resources. This way you can emphasize any point you want in the main README and leave the other less used documentation for elsewhere.
On Sunday, May 10, 2020 19:43 +03, Jacques Le Roux <ja...@les7arts.com> wrote:
Hi,
We often get questions from people not reading the basic documentation. Like not able to run Gradle because ignoring init-gradle-wrapper scripts.
I know there will always people not reading the documentation. But maybe, to prevent most obvious questions and tempting RTFM answers, we could add a
small README.TXT with basic information in OFBiz root.
It would ultimately refer to README.adoc. Also saying that README.adoc can be read with a text reader tool. And it's easy to follow
https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
What do you think?
Jacques