On 06/02/2015 11:59 AM, Arthur Schwarz wrote:
> 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.

I haven't yet seen any pdf, so it's hard for me to state what you are
referring to.

> Open Office offers several alternative output representations for a
> document, to wit

Indeed.  But as always in open source, it is better to post your
original preferred editing form (OpenOffice .odt is a portable format,
well supported on GNU/Linux systems) than it is to post any derived
forms (whether that be .pdf, .rtf, or even non-free formats like .doc),
especially if the derived forms lose information or are harder to edit
than the original.  Still, someone would have to translate that work
from OpenOffice into .texinfo for incorporation with the rest of the
manual.  In particular, while .odt is a portable format, it is still a
binary format and occupies a lot of space in a .git repository and is
hard to diff between revisions without installing additional tools;
whereas a plain-text format like .texinfo occupies less space and can be
diff'd using the same tools as on source code.

By all means, post your work.  All I'm saying is that you can accelerate
the acceptance of your work by making it in a format that is easier to
incorporate.  We're not going to outright reject your work, just because
we can't drop it in.  And if your work is truly as amazing as you are
making it out to be, then someone else will step up and help in the
transformation efforts.

> 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'.

We'd be glad to help you learn how to incorporate figures into .texinfo.

It would also help to know what original source your drawings are in.
For example, .fig is better than most other formats, because it is an
all-text representation rather than a binary (of course, directly
editing a .fig is not trivial; it's best to open up a decent graphics
editor, make changes, and then save back as .fig); a .png is portable
but binary and not easily edited.  If you are making your figures
directly in OpenOffice (or LibreOffice these days, now that OpenOffice
is falling out of favor in open source communities), I'm not sure how
easy or hard it is to save them out into a more reusable format like .fig.

> 
> 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.

Without even seeing the 'suggested' changes, it's hard to make any sort
of judgment call.

I'm not trying to discourage you - by all means, PLEASE continue to
contribute, and make the documentation better.  Free software is more
powerful because anyone can scratch their itch, and your itch is the
quality of documentation.  All I'm trying to do is to make you aware
that you can't expect overnight adoption of your new work, especially if
it is not yet in a format that will drop in place of the older text.

Also, I am not the automake maintainer, but I do have commit access, and
I am also aware that the official listed maintainer has been very
hard-pressed for time lately to make much of any response on list.  I do
not want to become the maintainer, but I can help shepherd patches in,
provided that they do not become a time sink on my end.  That means that
if I'm the one stuck transcribing .odt into .texinfo, it probably won't
happen, but lack of my time should not be construed as rejection of your
work.

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