Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Xue Fuqiao]

On Thu, Apr 25, 2013 at 3:02 PM, Glenn Morris <address@hidden> wrote:
>
> Hi,

Hi,

> Some comments. I only commented on the things I disagreed with, so this
> is probably going to come across as negative, sorry.

No need to be sorry.  Pointing out my faults can make me grow up, thank
you.

> I also think I'm probably not in the best position to assess a
> document about motivating people to get involved in Emacs (if that is
> the intent).

Yes, that's the intent.

> My main comment is that it seems rather disjointed, and tries to cover
> way, way too much. You've got stuff ranging from basic info about how to
> post on a mailing list, to very dry technical details about stylistic
> conventions used in Emacs, to "there's this thing called grep" basic
> UNIX stuff. As it stands, I don't think I see a place for it as an Emacs
> manual, it's just too unfocused.

> A lot of it is copied (without attribution)

That's true.  Since I began to write this guide about two weeks ago, I
haven't had time refining it yet.

> from GNU standards, Emacs files such as README, etc/CONTRIBUTE,
> admin/notes, and many other places. This is just lots and lots of
> pointless duplication. It would be much better to just refer to those
> documents, unless your aim is to replace all of them with one
> uber-document, which would be a huge job and not very valuable IMO. I
> have to say that I prefer the style of etc/CONTRIBUTE as a shorter
> document that just tries to tell you the basics of what you need to
> know to start getting involved.

I think we should include *some* (at least more than etc/CONTRIBUTE)
basics.  If etc/CONTRIBUTE is that useful, there won't be much questions
about contributing to Emacs.  (The style of etc/CONTRIBUTE is good, tho.)

BTW (sorry if it's off-topic) I think it is also a problem with Emacs
manual.  It is written with 1980's mindset, many nodes are in a verbose
way and can be edited out as improvement.  (Like `real-time display',
this feature is in most modern editors today.)

> I do think that it would be valuable to have some kind of hacking Emacs
> guide, that tells you everything you need to know about how to commit to
> Emacs, but I think that should be a separate document.

Agreed.  Maybe it can be based on this document:
http://www.emacswiki.org/emacs/HackerGuide

> There's that as one document, and the contributing to the Emacs
> community stuff that you start with as another, and then Emacs coding
> conventions etc which are largely covered elsewhere already IMO.

Agreed, that's a great problem I'm trying to resolve.  (But not now.
I'm really busy these days.)

>   @set AUTHOR Xue Fuqiao
>
> Unused?

Yes, it can be removed.

>   updated for Emacs version @value{EMACSVER}.
>
> Is EMACSVER really relevant? If not, it's simpler to do without it.

I didn't think much here.  Maybe this document is not similiar to
emacs.texi/elisp.texi/faq.texi.

>   People involved with the Emacs community have differing political,
>   social, economic and ethnic backgrounds. We work across timezones,
>   languages, and cultures. The success of Emacs depends on participation
>   from people like you. Find out how you can get involved to help make a
>   difference in the lives of users everywhere in the future.
>
> I'm sorry, but I really dislike this language. It seems irrelevant,
> obvious, and over-the-top. The preceding sentence ("GNU Emacs is a
> collaborative project and we encourage contributions from anyone", lifted
> from etc/CONTRIBUTE) says all that needs to be said IMO.

This sentence is originally "GNU is a collaborative project and we
encourage contributions from anyone", but I think it is not quite
relavant to Emacs.  I take your advice.

>   Emacs have a community of enthusiastic volunteers trying to support
>   our users around the globe.
>
> s/have/has
> s/trying to support/supporting

Thanks.

>   Join us for an incredible adventure!
>
> Sorry, this sounds silly to me. It's hacking on a text editor. If you
> enjoy hacking on text editors, you might find it enjoyable. If you
> don't, you probably won't. It's not finding the source of the Nile.
> (Ignore me if I'm just too negative and everyone else thinks this is fine.)

Maybe "Happy hacking!"?

>   You can find questions from mailing lists (like 
> @uref{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs,help-gnu-emacs} 
> and
>   
> @uref{https://lists.gnu.org/mailman/listinfo/help-emacs-windows,help-emacs-windows}),
>  newsgroups (like comp.emacs and
>   gnu.emacs.help), websites (like 
> @uref{http://stackoverflow.com/questions/tagged/?tagnames=emacs&sort=newest,Stack
>  Overflow}), and IRC channels
>   (like @verb{~#emacs~} and @verb{~#gnus~} on Freenode).
>
> Maybe you want to mention that gnu.emacs.help == help-gnu-emacs

We can mention https://savannah.gnu.org/mail/?group=emacs here and add
information about IRC and StackOverflow (not sure whether it is
considered as advertising).

>   Rather than trying to figure out the user's problem by yourself
>   every time, first search to see if it has come up before.  Try to
>   search the Emacs manuals before anything else.  If the manuals
>   don't have your answers, you can use other sources.
>
> "Do the work people are too lazy to do for themselves."
>
>   If you find out the solution, consider adding it to the Emacs FAQ.
>
> The Emacs FAQ is kind of useless IMO.

You've mentioned it here:
http://debbugs.gnu.org/cgi/bugreport.cgi?bug=13401#14

But this is exactly the reason why we should improve it.  (Or obsolete
it?)

>  This advice seems oddly out of place, because while anyone can do the
> previous steps you've outlined till now, this one needs commit rights.

Can we move it later in this guide?

>   Be nice.  If you feel that a post has crossed the line, report
>   it to the Emacs maintainers.
>
> No. This is a) obvious, and not special to Emacs, so hardly needs to be
> mentioned IMO; and b) I do not want to get mails from people complaining
> that someone was mean to them on Stack Overflow or wherever. Report it
> to whoever moderates the communication medium you are using (if a
> mailing list, this is the list owner). If no-one does, ignore the
> offending party and move on.

Sounds fine to me, I'll improve it.

>    Subscribing to the
>    @uref{http://lists.gnu.org/mailman/listinfo/emacs-devel,emacs-devel}
>    mailing list is a good idea. It's a mailing list for communications
>    among Emacs developers.
>
> There's zero need to subscribe to this unless you are interested in
> Emacs development. If you just want to _use_ Emacs, then you can ignore
> this list.

Maybe a better version:

  If you are interested in the development of GNU Emacs, you can
  subscribe to the
  @uref{http://lists.gnu.org/mailman/listinfo/emacs-devel,emacs-devel}
  mailing list. It's a mailing list for communications among Emacs
  developers.


>   Don't post chain letters, marketing messages or other types of
>   non-topical spam.
>
> Obviously. What does this have to do with contributing to Emacs?

It can be moved to: https://savannah.gnu.org/mail/?group=emacs.  (If
Savane supports.)


>   Or validate web pages of Emacs.
> Not clear what this means.

A validator is a software program that can check your web pages against
the web standards.  See: http://validator.w3.org/

>   If you would like to help pretest Emacs releases to assure they work
>   well, or if you would like to work on improving Emacs, please contact
>   the maintainers at @email{emacs-devel@@gnu.org,emacs-devel@@gnu.org}. A
>   pretester should be prepared to investigate bugs as well as report them.
>
> There is zero need to mail this list if you want to pretest Emacs.
> Just do it.

It is copied from doc/emacs/trouble.texi.  Maybe we can remove it.

>   If you know HTML/CSS, you can contribute to the web pages of
>   Emacs and GNU ELPA.
>
> There is very little to do here IMO. Most of the Emacs web-pages are
> static or generated from Texinfo.

Agreed.  But since it does not occupy much space, IMHO it can be
reserved.

>   If you know C, you can contribute to a number of low-level
>   libraries
>
> Seems an odd statement.
>
>   and help us write Emacs primitives.
>
> Could be phrased better.

Do you have a better suggestion?  (Sorry for my poor English.)

>   Porting to new platforms is also useful.
>
> This comes up almost never, and is unlikely to be suitable for casual
> contributors, so hardly seems worth mentioning.

+1

>   If you think of new features to add to @verb{~etc/TODO~}, please
>   suggest them too.
>
> Not the best way to phrase it. If people think of new features, they
> should be reported as wishlist bugs. (But what we really need are people
> to implement ideas, not sit around brainstorming.)

I'll improve it.

>   Before contributing a new feature to Emacs, you should check to
>   make sure that the feature isn't already available.  (See 
> @uref{http://lists.gnu.org/archive/html/emacs-devel/2013-04/msg00180.html,this
>  thread}.)
>
> I have no idea why you link to that thread.

This is an example of duplicated implementations of the same feature.

>   For example, typing @verb{~M-x apropos <RET> humor <RET>~} lists
>   all functions and variables containing the string @verb{~humor~}; typing
>   @verb{~M-x list-packages~} command connects to the GNU ELPA
>   (@uref{http://elpa.gnu.org}) ("Emacs Lisp Package Archive") server and
>   fetches the list of additional packages that it offers.  These are
>   GNU packages that are available for use with Emacs, but are
>   distributed separately.  It is also possible that the package is on
>   your system, but has not been loaded.  To see which packages are
>   available for loading, look through your computer's Lisp directory.
>
> In all honesty, this could be summarized as "do a web search before
> spending time implementing something that already exists".

Sounds fine.  This guideline is the answer to questions like "how to
find a (existing) feature?".

>   Think carefully about whether your change requires updating the
>   documentation.  If it does, you can either do this yourself or add
>   an item to the NEWS file.
>
> Now you've suddenly jumped to stuff that is only relevant to people with
> commit rights.

Agreed.  The structure of this document needs many changes.

>   If you document your change in NEWS, please mark the NEWS entry
>   with the documentation status of the change: if you submit the
>   changes for the manuals, mark it with @verb{~+++~}; if it doesn't need to
>   be documented, mark it with @verb{~---~}; if it needs to be documented,
>   but you didn't submit documentation changes, leave the NEWS entry
>   unmarked.
>
> Now you are just copying stuff from NEWS.

A pointer is better, can you give a suggestion?

>   @footnote{These marks are checked by the Emacs maintainers to make
>   sure every change was reflected in the manuals.}
>
> If you are committing stuff to that file, you ARE the Emacs maintainers.
> Ie, everyone should think about documentation, rather than farming it out
> to some other sucker.

Sorry but I can't understand this paragraph, do you mean the paragraph
above should be removed?

>   They should follow our usual standards for web pages:
>
> I honestly can't think of a single case in the past ten years where
> someone has contributed a web page to Emacs, so I just can't see how
> this relevant to anyone. I assume it is mainly cribbed from
> http://www.gnu.org/server/fsf-html-style-sheet.html, so why not just
> refer to that rather than copying it?

I'll do some cleanup here.

>   @node Some Coding Conventions
>
> May as well just refer to the relevant section of the elisp manual
> rather than reproduce pieces of it.

+1

>   You can design themes, icons and web pages for Emacs.
>
> Themes ok, but what icons do we need?

Different icons for different themes.

> Again, I don't think web-pages design is needed (maybe this is my
> failing and there is lots that could be done here).

Well, most work can (and should) be done by GNU Webmaster team.  But
AFAIK the whole elpa.gnu.org (web page) is maintained by us, so it can
be improved by Emacs developers.

>   Proof-reading the manuals and man pages.  That's also a great way
>   to learn more about Emacs.  This is usually done together with
>   reading the NEWS file to make sure that the manual has been
>   updated.
>
> I'd lose the second sentence.

Why?  Sorry but I cannot agree with you here.

>   Generally the manual gives a bit less details but more background/context.
>
> Not sure I agree.

I'll remove it.

>   In Emacs tradition, we treat "point" as a proper name when it
>   refers to the current editing location.  It should not have an
>   article.  Thus, it is incorrect to write, "The point does not
>   move".  It should be, "Point does not move".  If you see "the
>   point" anywhere in Emacs documentation or comments, referring to
>   point, please fix it.
>
> This is just cribbed from admin/notes/documentation.
> Unless you want this to be the absolute definitive reference for Emacs
> coding, I can't see the point in mentioning such a dry, technical detail
> here.
>
>   Antinews is useful.
>
> (I disagree.) Again, this is just cribbed from admin/notes/documentation.
> I cannot see the point in mentioning this here. (One poor sucker has to
> try and update it just before a release, apart from that it's largely
> irrelvant.)

I'll add a pointer to admin/notes/ and do some cleanup here, thanks.

>   Emacs should not recommend, promote, or grant legitimacy to the use of
>   any non-free program. We can’t stop some people from writing
>   proprietary programs, or stop other people from using them, but we can
>   and should refuse to advertise them to new potential customers, or to
>   give the public the idea that their existence is ethical.
>
> I cannot see the relevance of this (copied from GNU standards) to your
> guide.

It's about documentation writing.  However, I'll remove it since there
is already a pointer to the GNU Coding Standards.

>   Never introduce new terminology in the middle of a complex
>   description, where each successive sentence builds upon what the
>   preceding ones said.  Always use @emph{exactly} the same words as in
>   the preceding sentences.
>
> This is just copied from a recent emacs-devel posting. Not sure it
> really fits.

Although it is not specific to Emacs, I think it is a useful tip for doc
writing.

>   Good spelling is encouraged.
>
> No, correct spelling and grammar is required, just like correct code is.
> But if you implement some new feature and your English is not best, it
> is much better if you at least try to document it, and ask for help with
> polishing, rather than leave someone else to do all the work.

I'll improve it, thanks.

>   Sentences should start with an uppercase letter.
>
> This is just the normal rule of English.

But many people do not respect it.

>   Don't mention in Antinews too many features absent in old versions.
>
> I imagine this is just copied from somewhere. It has no relevance to
> 99.99+% of people, so why mention it at all.

admin/notes/documentation.  I'll remove it.

>   To indicate possession, write Emacs's rather than Emacs'.  See
>   @uref{http://lists.gnu.org/archive/html/emacs-devel/2012-02/msg00649.html}
>
> True, but tedious.

I don't think so.  I think it's useful, not tedious.  Maybe the @uref
can be removed.

>   When you have all these pieces, bundle them up in a mail message and
>   send it to the developers. Sending it to
>   @email{bug-gnu-emacs@@gnu.org,bug-gnu-emacs@@gnu.org} (which is the
>   bug/feature list) is recommended, because that list is coupled to a
>   tracking system that makes it easier to locate patches. If your patch
>   is not complete and you think it needs more discussion, you might want
>   to send it to @email{emacs-devel@@gnu.org,emacs-devel@@gnu.org}
>   instead. If you revise your patch, send it as a followup to the
>   initial topic.
>
> Copied from etc/CONTRIBUTE, missing the introductory sentence about
> "several pieces", therefore doesn't really make sense.

I'll remove them and make a pointer to etc/CONTRIBUTE.

>   If installing changes written by someone else, make the ChangeLog entry
>   in their name, not yours. There is no need to make change log entries
>   for files such as NEWS, MAINTAINERS, and FOR-RELEASE.
>
> Not relevant to people without commit rights, ie to people just
> submitting patches.

My guide is not for every Emacs user.  However, it will be better if we
put the guidelines that needs write access into one node.

>   If your version of diff does not support these options, then get
>   the latest version of GNU Diff.
>
> I cannot believe this will be relevant for anyone.

Why?

>   or, as a last resort, uuencoded gzipped text.
>
> Irrelevant in this day and age.

Maybe we can also remove it from etc/CONTRIBUTE.

>    GNU Emacs Common Lisp Emulation.  See @ref{Top,,,cl,}.
>
> Hardly seems relevant for casual contributors.
>
>   CC Mode.
>    [...]
>   @uref{http://cedet.sourceforge.net/,CEDET}.  CEDET is a
>    [...]
>   @item  @uref{http://www.emacswiki.org/emacs/Icicles,Icicles}.
>
> I can't see the point of mentioning these.
>
>   Tags Tables.  See @ref{Tags,,,emacs,}.
>
> Can't see the relevance of this either.

They are very useful for programming in Emacs Lisp.

>    @uref{http://developer.gnome.org/gtk3/unstable/,GTK+ 3 Reference
>    Manual}, since GTK+ is the default X toolkit in GNU Emacs.
>
> Can't see the point. Obviously you read that if you are working with the
> Emacs Gtk toolkit integration, and don't need to be told it exists, and
> if you aren't, you don't.
>
>   @uref{http://www.libtiff.org/libtiff.html,Using The TIFF Library}
>
>   @uref{http://giflib.sourceforge.net/intro.html,Introduction to GIFLIB}
>
> Irrelevant IMO.

I'll remove them.

>   @item GNU build system. It helps Emacs developers make Emacs source
>   code portable to many Unix-like
>   address@hidden@uref{http://www.gnu.org/software/autoconf
>   
> /manual/address@hidden@uref{http://www.gnu.org/software/automake/manual/address@hidden@uref{http://www.gnu.org/software/gnulib/manual/}}
>
> Irrelevant unless you are working on that stuff, else obvious.
>
>    @item
>   @uref{http://ximbiot.com/cvs/manual/stable,HTML Cederqvist for CVS
>   stable release}.  The web pages of Emacs are kept in a CVS repository.
>
> Irrelevant to almost everybody.
>
>   @item @uref{http://www.gnu.org/software/make/manual/,GNU Make Manual}.
>   Make is a tool which controls the generation of executables and other
>   non-source files of Emacs from the source files.
>
> Irrelevant unless you are working on that stuff, else obvious.

E.g., I want to add this document to Emacs repo, but it needs knowledge
of GNU Make and GNU Texinfo (makeinfo).

>   @uref{http://gcc.gnu.org/onlinedocs/,GCC online documentation}. The
>   GNU Comp iler Collection (GCC) is a compiler system produced by the
>   GNU Project supporting various programming languages.
>
> Irrelevant/obvious.
>

"I want to build Emacs, but I don't know what does
`--enable-link-time-optimization' and `--enable-gcc-warnings' mean."

>   @item @uref{http://www.gnu.org/software/guile/manual/,GNU Guile
>   Reference Manual}. Guile, a dialect of Scheme, is the native language of
>   the GNU standard extension language interpreter.
>
> Irrelevant unless you are working on that stuff, else obvious.

I'll remove it.

>   @item @uref{http://www.gnu.org/software/grep/manual/,GNU Grep Manual}.
>   The @verb{~grep~} command searches one or more input files for lines
>   containing a match to a specified pattern. It is a very useful tool and
>   often used when developing Emacs.
>
> This is the point at which I begin to think I'm coming at this from
> totally the wrong perspective, because I really can't see the point of
> linking to the grep manual in a "how to contribute to Emacs" guide.

I'll remove it.  (I link to the grep manual because grep is really
useful when developing Emacs, and I think (info "(emacs) Grep
Searching") is poorly written.)

>   @menu
>   * How to report a bug?::
>   * How to comment on a bug?::
>   * How to close a bug?::
>   * How to set bug meta-data?::
>   @end menu
>
> Pretty sure all this is just copied from elsewhere.
> I'm not sure of the value of having everything in one massive document.

admin/notes/bugtracker

>   If you want to Cc someone, use an @verb{~X-Debbugs-CC~} header instead.
>
> Irrelevant for the vast majority of people.

I'll remove it.

>   @node Copyright
>   @chapter Copyright
>
> Mainly copied from etc/CONTRIBUTE.
>
>   Every non-trivial file distributed through the Emacs repository
>   should be self-explanatory in terms of copyright and license.
>
>   The definition of triviality is a little vague[...]
>
>    Legal advice says that we could, if we wished, put a license notice[...]
>
> I don't think any of these details belong here.

I'll remove them.

>   @node Emacs repositories
>   @chapter Emacs repositories
>   There are three official Emacs repositories: 
> @uref{http://bzr.savannah.gnu.org/lh/emacs/,Bazaar}, 
> @uref{http://web.cvs.savannah.gnu.org/viewvc/?root=emacs,CVS}, and 
> @uref{http://git.savannah.gnu.org/cgit/emacs.git,Git}.
>
> I disagree. The offical repo is Bazaar. (There is a read-only Git
> mirror, and the web pages live in CVS for technical reasons, and are not
> relevant to most people.)

I had thought about it before I wrote this sentence.  I think "official"
means it is provided by the emacs group in Savannah.

>     * Building Emacs::
>
> Read INSTALL? Do you really want to cover this here as well?

No, just a quick guide.  (It could say, "See INSTALL for detail".)

>   @node Emacs Directory Tree
>
> Copied from README and <subdir>/README. Seems like totally pointless
> duplication.

I'll change it to pointer(s).

>   @item
>   Each commit should correspond to a single change (whether spread
>   over multiple files or not).
>
> Copied from admin/notes/commits. Why not just reference it rather than
> duplicate it?

I'll change it.

>   @item
>   For historical interest only, here is an old-style advice for CVS logs:
>
> Seriously, why are you copying even this old stuff?

I'll remove it.

>   @item
>   elpa
>   The GNU Emacs package archive, at elpa.gnu.org, is managed using a
>   Bzr branch named "elpa", hosted on Savannah.  To check it out:
>
> Copied from admin/notes/elpa.

I'll remove it.

>   @item
>   You should identify each release with a pair of version numbers, a
>   major version and a minor.
>
> Who is this for?

I'll remove it.

>   @item
>   Non-source files that might actually be modified by building and
>   installing the program should @emph{never} be included in the
>   distribution.
>
> Who is this for?

For the guys who write build rules for Emacs.

>   @item
>   +1
>   The shortest way in the geek world to say "I agree with this" or
>   "This is a great idea".
>
> Annoying as hell, adds nothing, don't do it.

I'll remove it.

>   @item
>   DVCS
>
> Hardly seems relevant. I'm not sure what the point of any of these items
> are, to be honest. GSoC, IDE, IRC, UTC?! Why are you trying to explain
> these terms here?

Sorry, some terms here are my testing stuff.  I forgot to remove them.

BTW we can add a troubleshooting node, and even a refcard for Emacs
hackers.

It seems that there's too much stuff to fix.  Maybe we create a
contribute-guide branch...  (So we can do drafting, formatting,
submitting, reviewing, approving, distributing, repositing, tracking...
I can't fix all of them in the near future.)  And I'm thinking about
whether the new guide is linear or branching.

--
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/