Re: More metaproblem

[Stephen Leake]

Drew Adams <address@hidden> writes:

>> As you say below, I don't think we should duplicate the information
>> in the two files, but I would not be averse to moving the info
>> into the manual, and leaving ./CONTRIBUTE as a reference.
>
> If you agree that we should not duplicate the information, then
> why would you leave ./CONTRIBUTE?  That's duplication, no?

I meant "change the content of ./CONTRIBUTE to refer to the manual". So
people who look for a file CONTRIBUTE will still find the information.

>> > IMO, it does not matter whether such info is detailed, boring,
>> > internal stuff.  It would still be good to move it from other
>> > files to the official doc, and give it the proper love that
>> > such doc requires.
>> 
>> I consider ./CONTRIBUTE to _be_ "official doc". Why do you think
>> otherwise?
>
> It is official.  But it is not in Info form, and it deserves
> to be (users deserve it to be).  That's what I meant.  Perhaps
> I should have said "move it from other files to where
> the rest of the official is presented to users: in Info."

But the information in ./CONTRIBUTE is _not_ for users; it is for
developers. 

> My (personal) answer is that it should be in Info, not just
> on the web somewhere, and not just in a file in the Emacs
> distribution somewhere, and not just as a pointer to a mailing
> list somewhere.
>
> Imagine if all of the important Emacs documentation had only
> the form/accessibility you are referring to.  Would you be
> content to replace the Emacs manual (Info) with a link to a
> web page or a local plain-text file?  I wouldn't want that.

As an Emacs _user_, I agree, I want the Emacs user manual in Info.

As an Emacs _developer_, it makes some sense to use Info, but it should
be in a separate manual (as you allow below).

Texinfo is _almost_ as easy to edit as plain text, but there is some
cost. What is the actual gain?

You have to know the file is there, or know how to look for it. That's
why is was move up from etc/; easier to find. It's also why it's
referenced from the Emacs manual.

However, I agree an "Emacs developers manual" in the top-level Info menu
would be even easier to find.

Whether it is in info or plain text (or some other format) is a
secondary issue.

We are only talking about 330 lines, that have been in plain text for a
long time. Is there really a big reason to change?

I hear you saying that you prefer Info. I'm still not clear _why_ you
prefer Info, for this specific information.

I think you would reply "everyone that uses Emacs simply _expects_ all
documentation to be in Info". I can see why that might be true. I fall
back on "developers are not everyone" and "having different conventions
for developers and users makes it clearer which is which". Not very
strong points, I'll admit.

For me, it really comes down to ease of maintenance and use. I find the
plain text format slightly easier to both maintain and use (partly
because I have a C-F12 function that does 'find-file-or-url-at-point').
But if someone else wants to put in the time to move it to texinfo, I
won't object.

If the file gets much longer, I would want to move it to texinfo.

>> > 2. Let users know that they can contribute,
>> 
>> That is certainly implied by the Free Software nature of Emacs.
>
> I think you are missing the point of my suggestion.  Putting this
> information in the Emacs manual would make it much more visible
> to "ordinary" users (and much more navigable).  (IMHO)

(info "(emacs)Contributing")

Feel free to submit patches.

>> > 3. Encourage people to reference it, as they do now for
>> >    questions about key-binding conventions etc.
>> 
>> I don't see why
>> http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributin
>> g.html would be a better/simpler/easier reference than ./CONTRIBUTE.
>
> No one said it would be.  I think you have not understood my
> suggestion well enough.

You said "encourage people to reference it".

Hmm, since we are talking about info, the proper reference would be
(info "(emacs)Contributing"). Much better.

If it's a (slightly) longer string, that (slightly) discourages me from
referencing it.

Perhaps if everyone expects all docs to be in Info, you would feel
reluctant to reference something that is not in Info? That makes some
sense. 

>> If you need to read ./CONTRIBUTE, you already have the source on
>> your disk.
>
> Having the information on your disk is not enough.  Having it on
> the web is not enough.  It should be available from Emacs, 

It is, if it is on your disk.

> in Info form.

That is the issue under discussion.


>> Exception: the short list of "other ways to contribute" should be on
>> a web page somewhere.
>> 
>> > Just a thought.  Disclaimer: I'm not familiar with the
>> > info I'm conjecturing about.
>> 
>> Please take a moment to read it; it's only 339 lines, about 1/3
>> white space.
>
> I'm talking also about details that explain conventions and
> methods used for developing/maintaining Emacs.

Where are they? The ones I'm aware of are referenced from the current
trunk version of ./CONTRIBUTE. I am deliberately ignoring the wiki.

-- 
-- Stephe