Re: [PATCH] Add prettify symbols to python-mode

[Eli Zaretskii]

> Date: Thu, 24 Sep 2015 11:57:24 +0800
> From: Xue Fuqiao <address@hidden>
> Cc: address@hidden, Emacs-devel <address@hidden>
> 
> >> * Hacking on the C level is inherently more difficult than the Lisp
> >>   (application) level.
> >
> > I don't see why.  C is not a complicated language, and a large part of
> > the Emacs source code never touches its relatively more problematic
> > parts, like memory allocation.
> 
> Maybe because the display engine is so complex that people don't want to
> spend too much time on it.

It's not very complex, as long as you don't try to make too deep
changes in it, like a complete redesign.  Most of the time you don't
need a detailed understanding of the entire display design, just of
some small area you want to change.

And the display engine is just one part of the C code; there are quite
a few others, like searching, input handling, text properties, syntax,
the Lisp interpreter, etc.

> Although, Lisp code has documentation strings and the `;;; Commentary:'
> header, there's also lispref.  In-code documentation isn't enough
> sometimes.

Documentation is never enough.  The question is: is it a reasonably
good start?  I think in many parts of the C code we have now, it is,
although additions are always welcome, of course.

> For example, if a developer wants to hack on the display engine, first,
> she needs to know where the code of the display engine is (She may
> wonder, is character.c part of the display engine, which is used to
> display characters?  What about cmds.c?  composite.c?  disptab.h?
> emacs.c?  fringe.c?  image.c?  textprop.c?  And xdisp.c?)

The same problem exists for stuff implemented in Lisp.  And the
solution is the same: "C-h f" and "C-h v" for built-in functions and
variables relevant to the issue at hand will guide you to the source
file you are looking for, and the ELisp manual will describe the
purpose and effect they are supposed to have.  From those starting
points, use source browsing tools to find their subroutines, relevant
other functions, etc.

This text from CONTRIBUTE should be a starting point:

  ** Understanding Emacs Internals.

  The best way to understand Emacs Internals is to read the code,
  but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
  of the Emacs Lisp Reference Manual may also help.  Some source files,
  such as xdisp.c, have large commentaries describing the design and
  implementation in more detail.

  The file etc/DEBUG describes how to debug Emacs bugs.

> second, she wants to know how to debug a redisplay problem
> ("--enable-checking='yes,glyphs'"?  How to use its facilities?).

This is described in etc/DEBUG.

> She also need to know whether she can use C11 features

Covered in the ELisp manual (see the node "C Dialect" there).

> how to DEFUN

This is described in the ELisp manual, in the node "GNU Emacs
Internals".

> which language should the test suite be written in for C code
> (C or Lisp?)

Lisp is preferred, as always, but eventually it's up to the programmer
who writes the tests.

> and all kinds of details that long-time core hackers are familiar
> with but a newcomer doesn't have any clue.

You cannot demand to know everything before you start hacking; if you
do, you will never make any progress.  Find out enough to make the
first step, then make that step; then repeat for the next step.  Any
knowledge that is not immediately used in practice will be soon
forgotten, so it's futile to gather information you don't need to make
your next step.

> (To my understanding, the display engine is composed of xdisp.c,
>  dispnew.c, fringe.c, and perhaps some platform-dependent code like
>  nsfns.m, w32fns.c, and xfns.c.  Please correct me if I'm wrong.)

It depends on what you mean by "display engine".  The full list is
much longer:

  . core terminal-independent display code:

    xdisp.c, dispnew.c, bidi.c, dispextern.h, composite.[ch], scroll.c

  . terminal-specific back-ends:

    term.c, xterm.c, xfns.c, w32term.c, w2console.c, w32fns.c,
    nsterm.m, nsfns.m, msdos.c

  . text-mode terminal support code:

    terminal.c, termcap.c, terminfo.c, tparam.c, termhooks.h

  . font and complex script shaping support:

    font.c, fontset.c, ftfont.c, ftxfont.c, ftcrfont.c, xfont.c,
    xftfont.c, w32font.c, w32uniscribe.c, nsfont.m, macfont.m

  . faces: xfaces.c

  . fringes: fringe.c

  . images: image.c, nsimage.m

  . menus:

    menu.c, xmenu.c, term.c, w32menu.c, nsmenu.m, msdos.c