How to not contribute to GNOME LaTeX
====================================

Contributions are no longer welcomed and will not be reviewed or accepted. If
you want to work on gnome-latex, please fork the project. The reason is
because, from my experience, new maintainers want to add features that don't
follow the gnome-latex principles for the user experience [1], and I would
still like to use my application the way I've developed it. And in case I want
to come back and maintain again gnome-latex in the future, I would like it to
be in the same state that I've left it, to avoid the need to fork my own
project.

[1] https://blogs.gnome.org/swilmet/2012/08/19/latexila-some-principles-for-the-user-experience/

Notes to potential developers who want to fork gnome-latex
----------------------------------------------------------

I wrote the Vala code when I was a beginner, so some parts may be ugly and not
well implemented. The liblatexila, written in C, is much better implemented.

For the build tools, parsing the commands output is quite fragile, especially
the output of latexmk. And the latex post-processor is full of heuristics, some
warning/error messages are not extracted correctly. With retrospection, it was
a bad idea to implement it like that. To have a more robust implementation, it
would have been better to parse the log file and have a log viewer, see:
https://gitlab.gnome.org/GNOME/gnome-latex/issues/30
In general for my other projects I now try to avoid implementing features that
have a fragile implementation (i.e. something not based on stable APIs, or with
heuristics, etc).
For gnome-latex, if the build tools break in the future, a solution is to
create a container with an older version of TeX Live bundled (or at least an
older version of latexmk bundled).

Previous content of this file:
==============================

GNOME LaTeX is hosted on the GNOME GitLab instance, you can fork the repository
and then do a merge request:

    https://gitlab.gnome.org/GNOME/gnome-latex

Read the following wiki page to know the conventions for the commit messages:

    https://wiki.gnome.org/Git/CommitMessages

Code conventions
----------------

For consistency, there are some conventions to follow for the code.

For Vala and C:
    - No trailing spaces.
    - Use blank lines to space out blocks of code (only one blank line is enough).
    - Space out each case in a switch, i.e. have a blank line after each 'break;'.
    - As a general rule of thumb, when modifying a file use the same coding
      style of that file.

For Vala:
    - Indentation: 4 spaces.
    - Lines: 90 characters maximum (in some cases it can be a little more).
    - /* ... */ comments for delimiting code sections.
    - // ... comments otherwise (e.g. for explaining just one line).
    - Curly braces are always on a separate line.
    - For one-line blocks (if, for, while, etc), no curly braces.
    - Some spaces almost everywhere:
        - function (blah);              // not function(blah);
        - int num = 5;                  // not int num=5;
        - if (!foo)                     // not if(!foo)
        - for (int i = 0; i < max; i++) // not for(int i=0;i<max;i++)
        - etc...
    - Do not use 'var' for declaring variables, unless the type is very long.
      The type of a variable is useful to understand the code, it is a form of
      self-documentation.
    - Functions with a lot of parameters: when exceeding 90 characters, add a
      newline + one indentation level (the same for function declarations and
      function calls):

            function_call (a_long_parameter1, a_long_parameter2, a_long_parameter3,
                a_long_parameter4, a_long_parameter5, a_long_parameter6,
                a_long_parameter7, a_long_parameter8);

For C:
    - Follow the same coding style as GtkSourceView:
      https://git.gnome.org/browse/gtksourceview/tree/HACKING
    - No maximum line length (but short lines are better).
    - Function declarations: follow the same style as what the
      gcu-lineup-parameters script does, see:
      https://github.com/swilmet/gnome-c-utils
    - Function calls with a lot of parameters: one parameter per line, aligned
      on the opening parenthesis:

	function_call (a_long_parameter1,
		       a_long_parameter2,
		       a_long_parameter3);

      In some cases, groups of parameters can be on the same line, when the
      parameters are related (typically a string + value). For example with
      g_object_new() to set properties:

	return g_object_new (NAMESPACE_TYPE_CLASSNAME,
			     "property1", value1,
			     "property2", value2,
			     NULL);

    - Note that the GNU coding style was previously used, all the *.c files
      have been converted to the GtkSourceView coding style with the uncrustify
      config file (see the scripts/ directory in the GtkSourceView git
      repository). The uncrustify config file is maybe not perfect, if you see
      a problem the config file can be improved and re-run on all *.c files.
      The *.h files have *not* been adapted, because there is no script
      available to correctly format function prototypes with the GNOME
      conventions, so here is the rule: when you *modify* a *.h file, please
      convert it first to the GtkSourceView coding style (mainly to change the
      indentation to use tabs), thanks! That way, all the *.h files will be
      converted over time. And in the future there will maybe be a script to do
      it.
