[gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable

[gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable

[Pacho Ramos]

[-- Attachment #1.1: Type: text/plain, Size: 566 bytes --]

Currently, when people uses DOC_CONTENTS variable to place their desired
messages, they are automatically reformatted by "fmt" to get proper
messages (for example, splitting long lines).

But, in some cases, may be useful to disable this behavior and respect
strictly how DOC_CONTENTS was formatted, for example in that kind of
messages telling people to run a command and, then, requiring a new line
to be used. This can also be useful to append extra information to
DOC_CONTENTS when, for example, additional info is needed when enabling
a USE flag.



[-- Attachment #1.2: 1.patch --]
[-- Type: text/x-patch, Size: 877 bytes --]

--- /home/pacho/gentoo-x86/eclass/readme.gentoo.eclass	2013-01-24 22:38:41.000000000 +0100
+++ ./readme.gentoo.eclass	2013-01-27 14:51:58.000000000 +0100
@@ -36,6 +36,12 @@
 
 EXPORT_FUNCTIONS src_install pkg_postinst
 
+# @ECLASS-VARIABLE: DISABLE_AUTOFORMATTING
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# If non-empty, DOC_CONTENTS information will be strictly respected,
+# not getting it automatically formatted by fmt.
+
 # @ECLASS-VARIABLE: FORCE_PRINT_ELOG
 # @DEFAULT_UNSET
 # @DESCRIPTION:
@@ -53,7 +59,11 @@
 	if [[ -n "${DOC_CONTENTS}" ]]; then
 		eshopts_push
 		set -f
-		echo ${DOC_CONTENTS} | fmt > "${T}"/README.gentoo
+		if [[ -n "${DISABLE_AUTOFORMATTING}" ]]; then
+			echo "${DOC_CONTENTS}" > "${T}"/README.gentoo
+		else
+			echo ${DOC_CONTENTS} | fmt > "${T}"/README.gentoo
+		fi
 		eshopts_pop
 		dodoc "${T}"/README.gentoo
 	else

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Pacho Ramos]

[-- Attachment #1.1: Type: text/plain, Size: 812 bytes --]

El dom, 27-01-2013 a las 15:00 +0100, Pacho Ramos escribió:
> Currently, when people uses DOC_CONTENTS variable to place their desired
> messages, they are automatically reformatted by "fmt" to get proper
> messages (for example, splitting long lines).
> 
> But, in some cases, may be useful to disable this behavior and respect
> strictly how DOC_CONTENTS was formatted, for example in that kind of
> messages telling people to run a command and, then, requiring a new line
> to be used. This can also be useful to append extra information to
> DOC_CONTENTS when, for example, additional info is needed when enabling
> a USE flag.
> 
> 

Well, after reading man echo I see all this is not needed, I simply need
to use echo -e to get it understand "\n" to create new lines

New patch attached

[-- Attachment #1.2: 1.patch --]
[-- Type: text/x-patch, Size: 428 bytes --]

--- /home/pacho/gentoo-x86/eclass/readme.gentoo.eclass	2013-01-24 22:38:41.000000000 +0100
+++ /usr/portage/eclass/./readme.gentoo.eclass	2013-01-27 18:41:40.000000000 +0100
@@ -53,7 +53,7 @@
 	if [[ -n "${DOC_CONTENTS}" ]]; then
 		eshopts_push
 		set -f
-		echo ${DOC_CONTENTS} | fmt > "${T}"/README.gentoo
+		echo -e ${DOC_CONTENTS} | fmt > "${T}"/README.gentoo
 		eshopts_pop
 		dodoc "${T}"/README.gentoo
 	else

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 896 bytes --]

On Sunday 27 January 2013 12:47:28 Pacho Ramos wrote:
> El dom, 27-01-2013 a las 15:00 +0100, Pacho Ramos escribió:
> > Currently, when people uses DOC_CONTENTS variable to place their desired
> > messages, they are automatically reformatted by "fmt" to get proper
> > messages (for example, splitting long lines).
> > 
> > But, in some cases, may be useful to disable this behavior and respect
> > strictly how DOC_CONTENTS was formatted, for example in that kind of
> > messages telling people to run a command and, then, requiring a new line
> > to be used. This can also be useful to append extra information to
> > DOC_CONTENTS when, for example, additional info is needed when enabling
> > a USE flag.
> 
> Well, after reading man echo I see all this is not needed, I simply need
> to use echo -e to get it understand "\n" to create new lines

printf '%b' "${foo}"
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Pacho Ramos]

[-- Attachment #1: Type: text/plain, Size: 2034 bytes --]

El dom, 27-01-2013 a las 13:05 -0500, Mike Frysinger escribió:
> On Sunday 27 January 2013 12:47:28 Pacho Ramos wrote:
> > El dom, 27-01-2013 a las 15:00 +0100, Pacho Ramos escribió:
> > > Currently, when people uses DOC_CONTENTS variable to place their desired
> > > messages, they are automatically reformatted by "fmt" to get proper
> > > messages (for example, splitting long lines).
> > > 
> > > But, in some cases, may be useful to disable this behavior and respect
> > > strictly how DOC_CONTENTS was formatted, for example in that kind of
> > > messages telling people to run a command and, then, requiring a new line
> > > to be used. This can also be useful to append extra information to
> > > DOC_CONTENTS when, for example, additional info is needed when enabling
> > > a USE flag.
> > 
> > Well, after reading man echo I see all this is not needed, I simply need
> > to use echo -e to get it understand "\n" to create new lines
> 
> printf '%b' "${foo}"
> -mike

The problem is that it doesn't work so well. If I have the following at
src_prepare (for example):
src_prepare() {
        DOC_CONTENTS="You must create a symlink rom /etc/splash/tuxonice
to the theme you want tuxonice to use, e.g.: \n
       		# ln -sfn /etc/splash/emergence /etc/splash/tuxonice \n"
...

and I handle ${DOC_CONTENTS} with quotes, it will end writing that tabs
also in generated file as the contents of the variable will be put
as-is. On the other hand, if I don't put it between quotes and, later,
pass "fmt", it will be formatted properly, without tabs and jumping to a
new line when \n is passed. In this way, echo will output a long line
with all the contents jumping to a new line when \n is found and, later,
fmt does the formatting.

But, if I use printf instead of echo:
1. If I put the variable with quotes it will be printed as-is (with
tabs).
2. If I drop the quotes, all spaces are dropped and end up with
something like:
Youmustcreateasymlinkfrom/etc/splash/tuxonicetothethemeyou


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 843 bytes --]

On Sunday 27 January 2013 13:21:27 Pacho Ramos wrote:
> The problem is that it doesn't work so well. If I have the following at
> src_prepare (for example):
> src_prepare() {
>         DOC_CONTENTS="You must create a symlink rom /etc/splash/tuxonice
> to the theme you want tuxonice to use, e.g.: \n
>        		# ln -sfn /etc/splash/emergence /etc/splash/tuxonice \n"
> ...
> 
> and I handle ${DOC_CONTENTS} with quotes, it will end writing that tabs
> also in generated file as the contents of the variable will be put
> as-is. On the other hand, if I don't put it between quotes

forcibly normalizing whitespace for all callers is wrong imo (as is sending it 
through `fmt`).  if the caller gave you content to write, it should write it.  
if the caller didn't want tabs, it shouldn't have used it in the first place.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Ben de Groot]

On 28 January 2013 12:37, Mike Frysinger <vapier@gentoo.org> wrote:
> On Sunday 27 January 2013 13:21:27 Pacho Ramos wrote:
>> The problem is that it doesn't work so well. If I have the following at
>> src_prepare (for example):
>> src_prepare() {
>>         DOC_CONTENTS="You must create a symlink rom /etc/splash/tuxonice
>> to the theme you want tuxonice to use, e.g.: \n
>>                       # ln -sfn /etc/splash/emergence /etc/splash/tuxonice \n"
>> ...
>>
>> and I handle ${DOC_CONTENTS} with quotes, it will end writing that tabs
>> also in generated file as the contents of the variable will be put
>> as-is. On the other hand, if I don't put it between quotes
>
> forcibly normalizing whitespace for all callers is wrong imo (as is sending it
> through `fmt`).  if the caller gave you content to write, it should write it.
> if the caller didn't want tabs, it shouldn't have used it in the first place.
> -mike

I've started using this eclass, but with README files, not the variable,
because this is currently the only way I can make sure it honours my
formatting.

-- 
Cheers,

Ben | yngwin
Gentoo developer
Gentoo Qt project lead, Gentoo Wiki admin

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Pacho Ramos]

[-- Attachment #1: Type: text/plain, Size: 1384 bytes --]

El lun, 28-01-2013 a las 14:37 +0800, Ben de Groot escribió:
> On 28 January 2013 12:37, Mike Frysinger <vapier@gentoo.org> wrote:
> > On Sunday 27 January 2013 13:21:27 Pacho Ramos wrote:
> >> The problem is that it doesn't work so well. If I have the following at
> >> src_prepare (for example):
> >> src_prepare() {
> >>         DOC_CONTENTS="You must create a symlink rom /etc/splash/tuxonice
> >> to the theme you want tuxonice to use, e.g.: \n
> >>                       # ln -sfn /etc/splash/emergence /etc/splash/tuxonice \n"
> >> ...
> >>
> >> and I handle ${DOC_CONTENTS} with quotes, it will end writing that tabs
> >> also in generated file as the contents of the variable will be put
> >> as-is. On the other hand, if I don't put it between quotes
> >
> > forcibly normalizing whitespace for all callers is wrong imo (as is sending it
> > through `fmt`).  if the caller gave you content to write, it should write it.
> > if the caller didn't want tabs, it shouldn't have used it in the first place.
> > -mike
> 
> I've started using this eclass, but with README files, not the variable,
> because this is currently the only way I can make sure it honours my
> formatting.
> 

Couldn't it be covered if "echo -e" was used (even with fmt) and you,
then, control formatting with some of the sequences it allows (they are
shown in its man page)?

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 1739 bytes --]

On Monday 28 January 2013 14:30:06 Pacho Ramos wrote:
> El lun, 28-01-2013 a las 14:37 +0800, Ben de Groot escribió:
> > On 28 January 2013 12:37, Mike Frysinger wrote:
> > > On Sunday 27 January 2013 13:21:27 Pacho Ramos wrote:
> > >> The problem is that it doesn't work so well. If I have the following
> > >> at src_prepare (for example):
> > >> src_prepare() {
> > >> 
> > >>         DOC_CONTENTS="You must create a symlink rom
> > >>         /etc/splash/tuxonice
> > >> to the theme you want tuxonice to use, e.g.: \n
> > >>                       # ln -sfn /etc/splash/emergence
> > >>                       /etc/splash/tuxonice \n"
> > >> ...
> > >> 
> > >> and I handle ${DOC_CONTENTS} with quotes, it will end writing that
> > >> tabs also in generated file as the contents of the variable will be
> > >> put as-is. On the other hand, if I don't put it between quotes
> > > 
> > > forcibly normalizing whitespace for all callers is wrong imo (as is
> > > sending it through `fmt`).  if the caller gave you content to write,
> > > it should write it. if the caller didn't want tabs, it shouldn't have
> > > used it in the first place.
> > 
> > I've started using this eclass, but with README files, not the variable,
> > because this is currently the only way I can make sure it honours my
> > formatting.
> 
> Couldn't it be covered if "echo -e" was used (even with fmt) and you,
> then, control formatting with some of the sequences it allows (they are
> shown in its man page)?

how is it better to require people to fill the string with \x20\n\t than to 
respect what was given ?  if people want to normalize whitespace themselves, 
they could just as easily do the `echo` themselves.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Ben de Groot]

On 29 January 2013 03:30, Pacho Ramos <pacho@gentoo.org> wrote:
> El lun, 28-01-2013 a las 14:37 +0800, Ben de Groot escribió:
>> I've started using this eclass, but with README files, not the variable,
>> because this is currently the only way I can make sure it honours my
>> formatting.
>>
>
> Couldn't it be covered if "echo -e" was used (even with fmt) and you,
> then, control formatting with some of the sequences it allows (they are
> shown in its man page)?

No. The eclass should assume that DOC_CONTENTS is already correctly
formatted. If you must, you can add a convenience function for people
who do want reformatting, but this should NOT be the default. Please
don't make this eclass harder to use than it needs to be.

-- 
Cheers,

Ben | yngwin
Gentoo developer
Gentoo Qt project lead, Gentoo Wiki admin

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Pacho Ramos]

[-- Attachment #1: Type: text/plain, Size: 1628 bytes --]

El mar, 29-01-2013 a las 14:03 +0800, Ben de Groot escribió:
> On 29 January 2013 03:30, Pacho Ramos <pacho@gentoo.org> wrote:
> > El lun, 28-01-2013 a las 14:37 +0800, Ben de Groot escribió:
> >> I've started using this eclass, but with README files, not the variable,
> >> because this is currently the only way I can make sure it honours my
> >> formatting.
> >>
> >
> > Couldn't it be covered if "echo -e" was used (even with fmt) and you,
> > then, control formatting with some of the sequences it allows (they are
> > shown in its man page)?
> 
> No. The eclass should assume that DOC_CONTENTS is already correctly
> formatted. If you must, you can add a convenience function for people
> who do want reformatting, but this should NOT be the default. Please
> don't make this eclass harder to use than it needs to be.
> 

I can add a variable (and probably will), but would prefer to keep it
formatting messages by default, otherwise, how will you set DOC_CONTENTS
variable inside a pkg phase (instead of global scope) without adding
tabs to it? You can of course add it, but it will be read as something
like:
src_prepare() {
	DOC_CONTENTS="blablabla
blablabla"
	# Rest of src_prepare stuff
}

Also, autoformatting will help to prevent every package setting messages
with different lines length (in some cases really long lines that I
finally reported some bugs in the past to get them fitting in "standard"
80 characters per line). 

I would then switch to "echo -e" and also add a function (like my
original solution in this thread) to allow you to disable formatting if
you want

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 1523 bytes --]

On Tue, 29 Jan 2013 22:47:26 +0100
Pacho Ramos <pacho@gentoo.org> wrote:

> El mar, 29-01-2013 a las 14:03 +0800, Ben de Groot escribió:
> > On 29 January 2013 03:30, Pacho Ramos <pacho@gentoo.org> wrote:
> > > El lun, 28-01-2013 a las 14:37 +0800, Ben de Groot escribió:
> > >> I've started using this eclass, but with README files, not the variable,
> > >> because this is currently the only way I can make sure it honours my
> > >> formatting.
> > >>
> > >
> > > Couldn't it be covered if "echo -e" was used (even with fmt) and you,
> > > then, control formatting with some of the sequences it allows (they are
> > > shown in its man page)?
> > 
> > No. The eclass should assume that DOC_CONTENTS is already correctly
> > formatted. If you must, you can add a convenience function for people
> > who do want reformatting, but this should NOT be the default. Please
> > don't make this eclass harder to use than it needs to be.
> > 
> 
> I can add a variable (and probably will), but would prefer to keep it
> formatting messages by default, otherwise, how will you set DOC_CONTENTS
> variable inside a pkg phase (instead of global scope) without adding
> tabs to it? You can of course add it, but it will be read as something
> like:
> src_prepare() {
> 	DOC_CONTENTS="blablabla
> blablabla"
> 	# Rest of src_prepare stuff
> }

How about:

src_prepare() {
    DOC_CONTENTS=(
        "line 1"
        "line 2"
        "line 3"
    )
}

?

-- 
Best regards,
Michał Górny

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 316 bytes --]

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Ralph Sennhauser]

[-- Attachment #1: Type: text/plain, Size: 1438 bytes --]

On Tue, 29 Jan 2013 22:47:26 +0100
Pacho Ramos <pacho@gentoo.org> wrote:

> Also, autoformatting will help to prevent every package setting
> messages with different lines length (in some cases really long lines
> that I finally reported some bugs in the past to get them fitting in
> "standard" 80 characters per line). 

I agree with you, there should be consistency as far as reasonable.
Formatting certainly is a valid means. Some sort of <code> tags could
be used if formatting isn't desired. Ie similar to eclass-manpages.


The eclass blurb:
 readme.gentoo - An eclass for installing a README.gentoo doc file
 recording tips

I know it started out as CONFIGURATION, but README.gentoo is generic
enough to contain other package specific info a user or upstream
developer might be interested in. What I have in mind right now are
patches.

This could look like the following in an ebuild:
  README_GENTOO_PATCHES=( "${FILESDIR}"/*.patch )
  epatch "${README_GENTOO_PATCHES[@]}"

Then the eclass generates for each patch in README_GENTOO_PATCHES a
note within a standard section containing patch name, author, subject
line. This needs something similar enough to a git format patch to
magically work though, but might be a nice addition and would help the
goal of consistency. Also git-format-patch like patches are anyway
preferable to dangling patches with maybe a bug number in the ebuild
at best.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 490 bytes --]

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Ben de Groot]

On 30 January 2013 05:47, Pacho Ramos <pacho@gentoo.org> wrote:
> El mar, 29-01-2013 a las 14:03 +0800, Ben de Groot escribió:
>> On 29 January 2013 03:30, Pacho Ramos <pacho@gentoo.org> wrote:
>> > El lun, 28-01-2013 a las 14:37 +0800, Ben de Groot escribió:
>> >> I've started using this eclass, but with README files, not the variable,
>> >> because this is currently the only way I can make sure it honours my
>> >> formatting.
>> >>
>> >
>> > Couldn't it be covered if "echo -e" was used (even with fmt) and you,
>> > then, control formatting with some of the sequences it allows (they are
>> > shown in its man page)?
>>
>> No. The eclass should assume that DOC_CONTENTS is already correctly
>> formatted. If you must, you can add a convenience function for people
>> who do want reformatting, but this should NOT be the default. Please
>> don't make this eclass harder to use than it needs to be.
>>
>
> I can add a variable (and probably will), but would prefer to keep it
> formatting messages by default, otherwise, how will you set DOC_CONTENTS
> variable inside a pkg phase (instead of global scope) without adding
> tabs to it? You can of course add it, but it will be read as something
> like:
> src_prepare() {
>         DOC_CONTENTS="blablabla
> blablabla"
>         # Rest of src_prepare stuff
> }

I still prefer the eclass not to mess with formatting by default. You
can do what you want by

src_prepare() {
    DOC_CONTENTS="blabla
        indented content"
    # other stuff
}

src_install() {
    default
    readme.gentoo_reformat
}

> Also, autoformatting will help to prevent every package setting messages
> with different lines length (in some cases really long lines that I
> finally reported some bugs in the past to get them fitting in "standard"
> 80 characters per line).

Sometimes long lines are what is required. If not, then filing a bug
is the friendly solution.

-- 
Cheers,

Ben | yngwin
Gentoo developer
Gentoo Qt project lead, Gentoo Wiki admin

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Pacho Ramos]

[-- Attachment #1: Type: text/plain, Size: 2432 bytes --]

El mié, 30-01-2013 a las 21:24 +0800, Ben de Groot escribió:
> On 30 January 2013 05:47, Pacho Ramos <pacho@gentoo.org> wrote:
> > El mar, 29-01-2013 a las 14:03 +0800, Ben de Groot escribió:
> >> On 29 January 2013 03:30, Pacho Ramos <pacho@gentoo.org> wrote:
> >> > El lun, 28-01-2013 a las 14:37 +0800, Ben de Groot escribió:
> >> >> I've started using this eclass, but with README files, not the variable,
> >> >> because this is currently the only way I can make sure it honours my
> >> >> formatting.
> >> >>
> >> >
> >> > Couldn't it be covered if "echo -e" was used (even with fmt) and you,
> >> > then, control formatting with some of the sequences it allows (they are
> >> > shown in its man page)?
> >>
> >> No. The eclass should assume that DOC_CONTENTS is already correctly
> >> formatted. If you must, you can add a convenience function for people
> >> who do want reformatting, but this should NOT be the default. Please
> >> don't make this eclass harder to use than it needs to be.
> >>
> >
> > I can add a variable (and probably will), but would prefer to keep it
> > formatting messages by default, otherwise, how will you set DOC_CONTENTS
> > variable inside a pkg phase (instead of global scope) without adding
> > tabs to it? You can of course add it, but it will be read as something
> > like:
> > src_prepare() {
> >         DOC_CONTENTS="blablabla
> > blablabla"
> >         # Rest of src_prepare stuff
> > }
> 
> I still prefer the eclass not to mess with formatting by default. You
> can do what you want by
> 
> src_prepare() {
>     DOC_CONTENTS="blabla
>         indented content"
>     # other stuff
> }

But it will be recorded with indent in README.gentoo, what is not
desired.

> 
> src_install() {
>     default
>     readme.gentoo_reformat
> }
> 
> > Also, autoformatting will help to prevent every package setting messages
> > with different lines length (in some cases really long lines that I
> > finally reported some bugs in the past to get them fitting in "standard"
> > 80 characters per line).
> 
> Sometimes long lines are what is required. If not, then filing a bug
> is the friendly solution.
> 

In that case, you could set the variable to skip formatting as, the
preferred option is to keep them in standard length, and the exception
is to require longer lines (in that case they could be covered with the
variable) 

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable

[Dan Douglas]

[-- Attachment #1: Type: text/plain, Size: 1505 bytes --]

On Sunday, January 27, 2013 03:00:21 PM Pacho Ramos wrote:
> Currently, when people uses DOC_CONTENTS variable to place their desired
> messages, they are automatically reformatted by "fmt" to get proper
> messages (for example, splitting long lines).
> 
> But, in some cases, may be useful to disable this behavior and respect
> strictly how DOC_CONTENTS was formatted, for example in that kind of
> messages telling people to run a command and, then, requiring a new line
> to be used. This can also be useful to append extra information to
> DOC_CONTENTS when, for example, additional info is needed when enabling
> a USE flag.
> 

Why does this eclass even exist? Everything that it does can be done directly 
in an ebuild in a couple lines of code, except in a much less ugly manner. It 
doesn't help to generalize anything. If you want to copy a file and call dodoc 
then just do it, don't write a pointless wrapper that people then have to go 
and look up what it does in order to read your ebuilds. The only thing I see 
that's maybe useful is saving on the logic for checking REPLACING_VERSIONS.

You can get rid of all that UUOC / UUOE. The set -f and eshopts stuff is 
unnecessary. You should localize the variables that can be localized like 
ELINE.

Funnily, looking at the implementation of elog, it appears to already mangle 
its input by a pass of `echo -e', pointlessly reading lines and joining them 
back together again repeatedly. This is just horrible! I don't even...
-- 
Dan Douglas

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Pacho Ramos]

[-- Attachment #1.1: Type: text/plain, Size: 1031 bytes --]

El dom, 27-01-2013 a las 18:47 +0100, Pacho Ramos escribió:
> El dom, 27-01-2013 a las 15:00 +0100, Pacho Ramos escribió:
> > Currently, when people uses DOC_CONTENTS variable to place their desired
> > messages, they are automatically reformatted by "fmt" to get proper
> > messages (for example, splitting long lines).
> > 
> > But, in some cases, may be useful to disable this behavior and respect
> > strictly how DOC_CONTENTS was formatted, for example in that kind of
> > messages telling people to run a command and, then, requiring a new line
> > to be used. This can also be useful to append extra information to
> > DOC_CONTENTS when, for example, additional info is needed when enabling
> > a USE flag.
> > 
> > 
> 
> Well, after reading man echo I see all this is not needed, I simply need
> to use echo -e to get it understand "\n" to create new lines
> 
> New patch attached

This will add an option to disabling autoformatting to let people get
their doc_contents 100% respected if they want

[-- Attachment #1.2: 1.patch --]
[-- Type: text/x-patch, Size: 868 bytes --]

--- readme.gentoo.eclass	2013-01-24 22:38:41.000000000 +0100
+++ /usr/portage/eclass/readme.gentoo.eclass	2013-01-31 19:55:40.000000000 +0100
@@ -36,6 +36,12 @@
 
 EXPORT_FUNCTIONS src_install pkg_postinst
 
+# @ECLASS-VARIABLE: DISABLE_AUTOFORMATTING
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# If non-empty, DOC_CONTENTS information will be strictly respected,
+# not getting it automatically formatted by fmt.
+
 # @ECLASS-VARIABLE: FORCE_PRINT_ELOG
 # @DEFAULT_UNSET
 # @DESCRIPTION:
@@ -53,7 +59,11 @@
 	if [[ -n "${DOC_CONTENTS}" ]]; then
 		eshopts_push
 		set -f
-		echo ${DOC_CONTENTS} | fmt > "${T}"/README.gentoo
+		if [[ -n "${DISABLE_AUTOFORMATTING}" ]]; then
+			echo "${DOC_CONTENTS}" > "${T}"/README.gentoo
+		else
+			echo -e ${DOC_CONTENTS} | fmt > "${T}"/README.gentoo
+		fi
 		eshopts_pop
 		dodoc "${T}"/README.gentoo
 	else

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

[gentoo-dev] Re: readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable

[Duncan]

Dan Douglas posted on Thu, 31 Jan 2013 09:22:04 -0600 as excerpted:

> On Sunday, January 27, 2013 03:00:21 PM Pacho Ramos wrote:
>> [Discussion of DOC_CONTENTS var]
>> 
> Why does this eclass even exist? Everything that it does can be done
> directly in an ebuild in a couple lines of code, except in a much less
> ugly manner. It doesn't help to generalize anything. If you want to copy
> a file and call dodoc then just do it, don't write a pointless wrapper
> that people then have to go and look up what it does in order to read
> your ebuilds.

You appear to be missing the point.  The goal of the eclass isn't to copy 
a file; as you say, that's covered.  Instead, the current problem is the 
common PKG_POSTINST messages that appear time and time again as people 
upgrade, that are important the first time and for reference, but after 
the first time, they're mostly just noise that users learn to ignore as 
they've seen them many times before.  Of course, ignoring such messages 
becomes a problem when an ebuild actually prints something new and 
useful, and VERY important (like reconfigure before you reboot or your 
reboot won't go well!), as the maintainer now has no way to get THOSE 
messages across.

So we get solutions like enews, and PKG_PRETEND, and ebuilds requiring 
I_KNOW_WHAT_I_AM_DOING vars, etc, so they don't end up with unbootable 
systems because they ignored the one important new message in all the 
"noise" of messages they'd read a dozen times over, already.

But arguably, those are solutions to different problems.  The real 
problem here is that we repeat the same messages every time a package is 
installed, until they're just "noise" that many users eventually simply 
ignore, leaving package maintainers without a /reasonable/ way to 
communicate the really important stuff.

That's the problem this eclass is trying to solve, providing a(n eclass 
standardized) way for maintainers to print important messages the first 
time they apply, but also to log them to a common location for reference 
purposes so a user can go back and look them up a year and several 
updates later, if for example they mistakenly restored an old copy from 
backup, and end up needing to redo whatever once again.

Basically, a better elog.

It seems to have generally been agreed that such functionality would be 
useful and should be standardized in an eclass (or new EAPI, but an eclass 
is faster to deploy if it does the job).  Now the discussion is centering 
around getting it right.  Formatting the messages handed to it by default 
or not.  Cleaning up the proposed code.  Tweaking for corner cases not 
yet covered but easily covered with a small change now before there's 200 
packages calling it that must be changed if the way it's called changes 
slightly to accommodate that corner-case.  Etc.

> Funnily, looking at the implementation of elog, it appears to already
> mangle its input by a pass of `echo -e', pointlessly reading lines and
> joining them back together again repeatedly. This is just horrible! I
> don't even...

So you saw the comparison to elog, handling a message given it, and 
/still/ missed that the eclass was to create a NEW file in a standardized 
location, putting into it the content passed in, not simply copy an 
existing file?  Missed the forest for all the trees. =:^)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Ben de Groot]

On 1 February 2013 02:59, Pacho Ramos <pacho@gentoo.org> wrote:
> El dom, 27-01-2013 a las 18:47 +0100, Pacho Ramos escribió:
>> El dom, 27-01-2013 a las 15:00 +0100, Pacho Ramos escribió:
>> > Currently, when people uses DOC_CONTENTS variable to place their desired
>> > messages, they are automatically reformatted by "fmt" to get proper
>> > messages (for example, splitting long lines).
>> >
>> > But, in some cases, may be useful to disable this behavior and respect
>> > strictly how DOC_CONTENTS was formatted, for example in that kind of
>> > messages telling people to run a command and, then, requiring a new line
>> > to be used. This can also be useful to append extra information to
>> > DOC_CONTENTS when, for example, additional info is needed when enabling
>> > a USE flag.
>> >
>> >
>>
>> Well, after reading man echo I see all this is not needed, I simply need
>> to use echo -e to get it understand "\n" to create new lines
>>
>> New patch attached
>
> This will add an option to disabling autoformatting to let people get
> their doc_contents 100% respected if they want

How about using an "as-is" argument to readme.gentoo_create_doc?
That would be more concise. :-)

-- 
Cheers,

Ben | yngwin
Gentoo developer
Gentoo Qt project lead, Gentoo Wiki admin

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Michael Weber]

On 02/01/2013 10:55 AM, Ben de Groot wrote:
> On 1 February 2013 02:59, Pacho Ramos <pacho@gentoo.org> wrote:
>> El dom, 27-01-2013 a las 18:47 +0100, Pacho Ramos escribió:
>>> El dom, 27-01-2013 a las 15:00 +0100, Pacho Ramos escribió:
>>>> Currently, when people uses DOC_CONTENTS variable to place their desired
>>>> messages, they are automatically reformatted by "fmt" to get proper
>>>> messages (for example, splitting long lines).
>>>>
>>>> But, in some cases, may be useful to disable this behavior and respect
>>>> strictly how DOC_CONTENTS was formatted, for example in that kind of
>>>> messages telling people to run a command and, then, requiring a new line
>>>> to be used. This can also be useful to append extra information to
>>>> DOC_CONTENTS when, for example, additional info is needed when enabling
>>>> a USE flag.
>>>>
>>>>
>>>
>>> Well, after reading man echo I see all this is not needed, I simply need
>>> to use echo -e to get it understand "\n" to create new lines
>>>
>>> New patch attached
>>
>> This will add an option to disabling autoformatting to let people get
>> their doc_contents 100% respected if they want
> 
> How about using an "as-is" argument to readme.gentoo_create_doc?
> That would be more concise. :-)
> 
PLEASE, add "define DOC_CONTENTS in an non-global scope, use
src_prepare/pkg_setup instead" to the eclass documentation of
readme.gentoo_print_elog, Thanks

++ for the eclass, the README.gentoo might submerge into the users
handling of Gentoo Systems. (I always laughed about README.Debian)
[1] show an report about exactly the non-atomar situation of elog and
application usage.

While [2] complained about elog cluttering, I try to migrate
x11-wm/xpra-0.8.0 (upcoming), am I doing it right?

DOC_CONTENTS="""
please make your Xorg binary readable for users of xpra
  chmod a+r /usr/bin/Xorg
and think about the security impact
A copy at ~/.xpra/Xorg matching the current modules is sufficient.
"""

^^ clearly would benefit from non-formatting.
repoman full complains about "Ebuild contains leading spaces on line".

[1] https://bugs.gentoo.org/show_bug.cgi?id=448588
[2] https://bugs.gentoo.org/show_bug.cgi?id=440464


-- 
Michael Weber
Gentoo Developer
web: https://xmw.de/
mailto: Michael Weber <xmw@gentoo.org>

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Pacho Ramos]

[-- Attachment #1: Type: text/plain, Size: 1497 bytes --]

El vie, 01-02-2013 a las 17:55 +0800, Ben de Groot escribió:
> On 1 February 2013 02:59, Pacho Ramos <pacho@gentoo.org> wrote:
> > El dom, 27-01-2013 a las 18:47 +0100, Pacho Ramos escribió:
> >> El dom, 27-01-2013 a las 15:00 +0100, Pacho Ramos escribió:
> >> > Currently, when people uses DOC_CONTENTS variable to place their desired
> >> > messages, they are automatically reformatted by "fmt" to get proper
> >> > messages (for example, splitting long lines).
> >> >
> >> > But, in some cases, may be useful to disable this behavior and respect
> >> > strictly how DOC_CONTENTS was formatted, for example in that kind of
> >> > messages telling people to run a command and, then, requiring a new line
> >> > to be used. This can also be useful to append extra information to
> >> > DOC_CONTENTS when, for example, additional info is needed when enabling
> >> > a USE flag.
> >> >
> >> >
> >>
> >> Well, after reading man echo I see all this is not needed, I simply need
> >> to use echo -e to get it understand "\n" to create new lines
> >>
> >> New patch attached
> >
> > This will add an option to disabling autoformatting to let people get
> > their doc_contents 100% respected if they want
> 
> How about using an "as-is" argument to readme.gentoo_create_doc?
> That would be more concise. :-)
> 

I have no problem on either solution... but don't have time just now to
work on a patch to achieve it, if you have a bit time, I would really
appreciate :)

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: readme.gentoo.eclass: use echo -e instead of plain echo (Was: Re: [gentoo-dev] readme.gentoo.eclass: Add a DISABLE_AUTOFORMATTING variable=

[Pacho Ramos]

[-- Attachment #1: Type: text/plain, Size: 1607 bytes --]

El vie, 01-02-2013 a las 21:34 +0100, Pacho Ramos escribió:
> El vie, 01-02-2013 a las 17:55 +0800, Ben de Groot escribió:
> > On 1 February 2013 02:59, Pacho Ramos <pacho@gentoo.org> wrote:
> > > El dom, 27-01-2013 a las 18:47 +0100, Pacho Ramos escribió:
> > >> El dom, 27-01-2013 a las 15:00 +0100, Pacho Ramos escribió:
> > >> > Currently, when people uses DOC_CONTENTS variable to place their desired
> > >> > messages, they are automatically reformatted by "fmt" to get proper
> > >> > messages (for example, splitting long lines).
> > >> >
> > >> > But, in some cases, may be useful to disable this behavior and respect
> > >> > strictly how DOC_CONTENTS was formatted, for example in that kind of
> > >> > messages telling people to run a command and, then, requiring a new line
> > >> > to be used. This can also be useful to append extra information to
> > >> > DOC_CONTENTS when, for example, additional info is needed when enabling
> > >> > a USE flag.
> > >> >
> > >> >
> > >>
> > >> Well, after reading man echo I see all this is not needed, I simply need
> > >> to use echo -e to get it understand "\n" to create new lines
> > >>
> > >> New patch attached
> > >
> > > This will add an option to disabling autoformatting to let people get
> > > their doc_contents 100% respected if they want
> > 
> > How about using an "as-is" argument to readme.gentoo_create_doc?
> > That would be more concise. :-)

But, how could people then active that "as-is" option without needing to
write a src_install function calling readme.gentoo_create_doc with that
option? 

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 198 bytes --]