bug#20714: tap-driver.sh outputs incorrect .trs tag

[Arthur Schwarz]

I appreciate your comments. The TAP pdf that I sent you is part of a larger
document. At the moment the document is 48 pages and is a complete
replacement for Section 15 up to dejaGnu which I haven't started yet. The
pdf was sent in lieu of the Open Office document, which is the genesis of
the pdf. Open Office offers several alternative output representations for a
document, to wit
o XML 1.0 Text Document (.sxw), 
o XML 1.0 Text Template (.stw), 
o Microsoft Word 87/2000/XP (.doc), 
o Microsoft Word 95 (.doc), 
o Microsoft Word 6.0 (.doc), 
o Rich Text Format (.rtf), 
o Text (.txt), 
o Text Encoded (.txt), 
o HTML Document (.html), 
o DocBook (.xml), 
o Microsoft Word 2003 XML (.xml), 
o Uniform Office Format 2 Text (.uot), 
o Unified Office Format Text (.uot).

The Open Office Document (.odt) is available.

If none of these formats are suitable then the document will be made
available for the community of users of Automake and Automake will not be a
participant. I've spent 5 months trying to understand Section 15 of the
Automake Manual, and during that time thought it best to rewrite it. The
Automake Manual as it stands is not significant and difficult to understand
without experimentation. My thoughts are that a document should be an
explanation of use rather than a result to be explored.

My document has tables and drawings. Something which seems missing from the
Automake Manual (and other Texinfo manuals). I have been told that there is
a mechanism to incorporate drawings and, perhaps, other objects into a
Texinfo document. But if the document is written with the same clarity as
Section 15 then my life is too short to understand and experiment with until
I 'Get it right'.

So, if the intent is to say that the maintainers are not in a position to
remove Section 15 and insert a new Section 15 then I think that we are in a
pickle. I am definitely not going to spend another 5 months providing
changes to an existing document, most particularly since there has been no
indication that the 'suggested' changes are acceptable.

Sorry.
art

-----Original Message-----
From: Eric Blake [mailto:address@hidden 
Sent: Tuesday, June 02, 2015 10:17 AM
To: Arthur Schwarz; 'Nick Bowler'
Cc: address@hidden
Subject: Re: bug#20714: tap-driver.sh outputs incorrect .trs tag

On 06/02/2015 10:24 AM, Arthur Schwarz wrote:
> A coupla' issues. I don't know Texinfo. I have included an extensive
> revision of the TAP testing cycle as a pdf file, downloaded from an Open
> Office Document.

While that may work, it is tedious to maintainers.  We have to figure
out which text you added or removed, then find the same text in the
upstream texinfo file and make the same edits.  And being a pdf, it may
be hard to copy and paste the changed text, making it all that harder.
You might make it easier by using color highlights or strikethrough
notations to call attention to your edits, but it is still not as
trivial as just having those edits already made in patch form against
the original upstream texinfo file.

If you want your patches to go in, it really WILL be better for you to
figure out how to directly patch the texinfo file.  It's not that hard
to figure out - it is a plain text representation with fairly obvious
markup for the most common tasks.  And we are more than willing to help
you with markup questions or with proof-reading, if we can start from a
patch that gets us 90% of the way to a final version without having to
do lots of copy-and-paste gyrations.  But if you just dump a .pdf file
of "here's the final product" without actually patching the upstream
source file, it will probably just be ignored, because in that case,
you'd have done only 10% of the work instead of 90%.  Like it or not,
free software works on a meritocracy principle, where the patches that
get applied are the ones written by people persistent enough to make the
maintainer's life easy.

For comparison, we prefer that someone says: "here are the changes to
your .c file to fix a bug", rather than "here is a complete .c file that
includes bug fixes but you have to locate what changed" or even "here is
a new binary that was compiled from a fixed .c file, but you have to
reverse engineer the binary to figure out what the changes were".

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org