RE: More metaproblem

[Drew Adams <drew.adams@oracle.com>]

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

Good.

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

Developers are users.  Some users are developers.  There is no
reason not to provide such info for users in general (IMHO).
Especially if we want to encourage users to contribute.

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

I don't have a problem with that.  My preference would probably
be to add it to the Emacs manual, a priori.  But I haven't heard
any argument to convince me that it should be in a separate
manual - perhaps I would change my mind if I did.

The argument that users are different from developers makes
little sense to me.  Might as well say that because some users
don't use the Calendar we should move all of the Calendar stuff
out of the Emacs manual into a separate one.  Or all of the
International stuff.  Or all of the Mail stuff.

Now there's a good candidate!  Move all of the Sending Mail,
Rmail, and Gnus stuff to a separate manual.  Yes, please. ;-)

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

What is the gain of having this information in Info form?  See
my previous messages.  Should be a no-brainer.  And the gain
of having it in the Emacs manual is to invite Emacs users to
consider contributing, and how to do so.

> You have to know the file is there, or know how to look for it.

That's another argument for moving the information to the manual.

> That's why is was move up from etc/; easier to find. It's also
> why it's referenced from the Emacs manual.

Why just reference it when you can include it?  Why use a
plain-text file when you can use Info?  And it will automatically
end up as HTML on the web, in the same location as the other
Emacs information.

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

OK.  I don't care which is considered primary and which secondary.
To me, both are good ideas: move it to Info, and put its node
link in the top-level `dir' menu or the top-level menu of the
Emacs manual.

> 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 imagine there are more than 330 lines for all of the "internal"
developer/contributor information.  At least I hope there are.

XEmacs has a nice internals manual, IIUC.  Doesn't GNU Emacs
deserve similar?

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

It is information for Emacs users on how to help develop Emacs.
We have some such info in the Elisp manual (the various
"conventions" nodes).  I think that other "developer" info
deserves a similar treatment, whatever manual it ends up in.

> I think you would reply "everyone that uses Emacs simply
> _expects_ all documentation to be in Info". 

I don't know whether they do.  But if you put it there they
will. ;-)  And why shouldn't they?

> I can see why that might be true. I fall back on "developers
> are not everyone" 

Not everyone uses Gnus, either.  Every developer is a user.
Some users contribute to development.  Some do so by filing
bugs.  Some by fixing bugs.  Some by testing bug fixes.
Some by maintaining releases & distribution.  Some by coming
up with new features (think how many features were originally
developed by users, in 3rd-party libraries - Emacs itself is
full of them).  

> and "having different conventions for developers and users
> makes it clearer which is which". Not very strong points,
> I'll admit.

It can only be clear in the sense of roles.  Now you wear
your user hat; now you wear your developer hat.  But yes,
the developer-oriented doc should be written with an Emacs
developer orientation, of course.  Just as the Elisp doc
is written with an Elisp user orientation.

> For me, it really comes down to ease of maintenance and use.

Use, fine.  Maintenance should not be a primary concern.
This is no different from maintaining and using any manual.

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

I hope someone does.  I think Emacs would benefit.  Just
one opinion.

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

Sorry; I don't know.  But if they were in the manual I would
be able to tell you.