\documentclass[12pt,a4paper]{article}

\input{version}

\def\qe{{\sc Quantum ESPRESSO}}
\sloppy
\usepackage{html}

% BEWARE: don't revert from graphicx for epsfig, because latex2html
% doesn't handle epsfig commands !!!
\usepackage{graphicx}
\usepackage{upquote}
\usepackage{color}
\usepackage[usenames,dvipsnames,svgnames,table]{xcolor}

\textwidth = 17cm
\textheight = 24cm
\topmargin =-1 cm
\oddsidemargin = 0 cm

\def\pwx{\texttt{pw.x}}
\def\cpx{\texttt{cp.x}}
\def\phx{\texttt{ph.x}}
\def\ppx{\texttt{pp.x}}
\def\nebx{\texttt{neb.x}}
\def\configure{\texttt{configure}}
\def\PWscf{\texttt{PWscf}}
\def\PHonon{\texttt{PHonon}}
\def\CP{\texttt{CP}}
\def\PostProc{\texttt{PostProc}}
\def\NEB{\texttt{PWneb}}
\def\make{\texttt{make}}
%\def\QEmodes{\texttt{QE-emacs-modes}}
\def\QEmodes{\texttt{QE-modes}}
\def\QEemodes{\texttt{QE-emacs-modes}}
\def\qemodes{\texttt{qe-modes}}

\def\efn#1{\textcolor{BlueViolet}{\texttt{#1}}}
\def\var#1{\textcolor{Blue}{\texttt{\textit{#1}}}}
\def\bvar#1{\texttt{\textit{#1}}}

\def\qemode{\efn{qe-mode}}
\def\nebmode{\efn{neb-mode}}
\def\pwmode{\efn{pw-mode}}
\def\cpmode{\efn{cp-mode}}
\def\phmode{\efn{ph-mode}}
\def\ldmode{\efn{ld1-mode}}
\def\ppmode{\efn{pp-mode}}
%\def\prmode{\efn{projwfc-mode}}

\begin{document} 
\author{}
\date{}

\def\qeImage{../../../Doc/quantum_espresso.png}

\title{
  \includegraphics[width=5cm]{\qeImage} \\
  % title
  \Huge \QEemodes\ User's Guide (v.\version) 
}

\maketitle

\tableofcontents

\section{Introduction}

This guide covers the usage of \QEemodes\ package (aka \QEmodes): an
open-source collection of Emacs major-modes for making the editing of
\qe\ (QE) input files somewhat easier and more comfortable with Emacs
editor. The package provides syntax highlighting (see
Figure~\ref{fig:example}), basic auto-indentation, and several utility
commands.

\section{Terms of use}

\QEmodes\ is free software, released under the
GNU General Public License. See:
\texttt{http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt}, or the
file \texttt{License} in the \qe\ distribution.

The \QEmodes\ package was written by Anton Kokalj. The implementation
of \QEmodes\ was made possible by several useful and helpful resources
that are gratefully acknowledged, in particular: {\it Mode Tutorial}
of Scott Andrew Borton
(\texttt{https://www.emacswiki.org/emacs/ModeTutorial} for indentation
code), {\it Derived Mode} and {\it Sample Mode} pages
(\texttt{https://www.emacswiki.org/emacs/DerivedMode},
\texttt{https://www.emacswiki.org/emacs/SampleMode}) as well as the
very useful resources of Xah Lee
(\texttt{http://ergoemacs.org/emacs/elisp\_syntax\_coloring.html}). Sebastijan
Peljhan is acknowledged for his work on \texttt{xsf-mode} that
inspired the idea of writing the \QEmodes. Last but not the least,
Hongyi Zhao contributed the \texttt{ido-completion-read} snippet of
Elisp code for selecting the values for the card's flags.

% TODO: add infro from the net.

\begin{figure}[htb]
  \centering
  \includegraphics[width=0.8\textwidth]{highlight.png}
  \caption{A \pwx\ input file opened with \pwmode\ in Emacs. Note the
    highlighted elements: namelists and their variables (blue and
    brown), cards and their flags (purple and green), comments (red),
    string and logical variable values (burgundy and cyan,
    respectively). Note that mistyped variable (i.e.\ \texttt{ibrv}
    instead of \texttt{ibrav}) is not highlighted.}
  \label{fig:example}
\end{figure}
    
\section{Installation}

The installation of \QEmodes\ package consists of two parts: (i)
installing the package itself and (ii) informing Emacs about it by
editing the \verb+user-init-file+ (typically \verb+$HOME/.emacs+).

\subsection{Installing the \QEmodes\ package}
Once the \texttt{QE-modes-\version.tar.gz} archive is unpacked and you
are located in its root directory, the installation is trivial. Simply use:
\begin{verbatim}
   ./install.sh
\end{verbatim}
which will install the package in the \qemodes\ subdirectory of the
\texttt{\$HOME/.emacs.d/} directory (the script copies the \QEmodes\
\texttt{*.el} files to \texttt{\$HOME/.emacs.d/} and byte-compiles
them into \texttt{*.elc} files).

If you prefer to install \QEmodes\ into other directory, use instead:
\begin{flushleft}
\verb+   prefix=+\var{where-to-install}\verb+ ./install.sh+
\end{flushleft}
which will install the package in the \qemodes\ subdirectory of
\var{where-to-install} directory.

% \paragraph{Note for non-Unix operating systems:} Given that
% \texttt{install.sh} is a shell script its execution may fail on
% non-Unix operating systems. In this case manually copy the \qemodes/
% subdirectory to appropriate place.

\subsection{Editing the \texttt{user-init-file} file}

A default \QEmodes\ snippet for \texttt{user-init-file} is provided by
the \texttt{qe-modes.emacs} file in the \QEmodes\ source package root
directory. If \QEmodes\ were installed in default
  \verb+$HOME/.emacs.d/qe-modes/+ location, {\bf then the
  \texttt{qe-modes.emacs} file can be used verbatim; just append its
  content to your \verb+~/.emacs+ file}.

Here is a the explanation of the simplified \texttt{qe-modes.emacs}
file.  Emacs is informed about the installed \QEmodes\ by the
following lines in the \verb+user-init-file+ (e.g.\
\verb+$HOME/.emacs+):
\begin{flushleft}
{\color{red}
\verb+   ;; make sure package is visible to emacs (if needed)+}\\
\verb+   (add-to-list 'load-path "+\var{/full/path/name/of}\verb+/qe-modes")+\\[1em]
{\color{red}
\verb+   ;; load the package+}\\
\verb+   (require 'qe-modes)+
\end{flushleft}
where \var{/full/path/name/of} is the directory where the \qemodes\
are installed (either the \texttt{\$HOME/.emacs.d/} or the above
\var{where-to-install}).


Furthermore, we can specify some filename patterns so that Emacs will
automatically recognize from the filename if it is some variant of the
\qe\ input file.
%
Say that we use the \verb+.in+ extension for the \qe\ input files in
general and more specifically, the \texttt{pw.}, \texttt{scf.},
\texttt{relax.}, and \texttt{vc-relax.} prefixes for the \pwx\ input files
and \texttt{neb.}, \texttt{cp.}, \texttt{ph.},  and \texttt{pp.} prefixes for the
\nebx, \cpx, \phx, and \ppx\ input files. These filename recognitions can be
achieved by:
\begin{flushleft}
{\color{red}
\verb+   ;; automatically open the *.in files with generic QE mode+}\\
\verb+   (add-to-list 'auto-mode-alist  '("\\.in\\'" . qe-mode))+\\[1em]
{\color{red}
\verb+   ;; automatically open the pw*.in, scf*.in, relax*in, vc-relax*.in files+\\
\verb+   ;; with pw.x mode+}\\
\verb+   (add-to-list 'auto-mode-alist  '("/pw.*\\.in\\'" . pw-mode))+\\
\verb+   (add-to-list 'auto-mode-alist  '("/scf.*\\.in\\'" . pw-mode))+\\
\verb+   (add-to-list 'auto-mode-alist  '("/relax.*\\.in\\'" . pw-mode))+\\
\verb+   (add-to-list 'auto-mode-alist  '("/vc-relax.*\\.in\\'" . pw-mode))+\\[1em]
{\color{red}
\verb+   ;; automatically open the neb*.in files with neb.x mode+}\\
\verb+   (add-to-list 'auto-mode-alist  '("/neb.*\\.in\\'" . neb-mode))+\\[1em]
{\color{red}
\verb+   ;; automatically open the cp*.in files with cp.x mode+}\\
\verb+   (add-to-list 'auto-mode-alist  '("/cp.*\\.in\\'" . cp-mode))+\\[1em]
{\color{red}
\verb+   ;; automatically open the ph*.in files with ph.x mode+}\\
\verb+   (add-to-list 'auto-mode-alist  '("/ph.*\\.in\\'" . ph-mode))+\\[1em]
{\color{red}
\verb+   ;; automatically open the pp*.in files with pp.x mode+}\\
\verb+   (add-to-list 'auto-mode-alist  '("/pp.*\\.in\\'" . pp-mode))+\\[1em]
\end{flushleft}
Beware that the more general \texttt{*.in} pattern for the generic
\qemode\footnote{Please note the difference between \qemodes\ and
  \qemode: the first implies the whole package, whereas the second
  means the generic QE mode, which is only one among the available
  modes in the \qemodes\ package.} should be specified first
or else any \texttt{*.in} file will be recognized as generic QE input
file.

For those who are fans of regular-expressions, the above four lines
for \pwmode\ can be expressed by the following one-liner:
{\footnotesize
  \begin{verbatim}
   (add-to-list 'auto-mode-alist '("/\\(pw\\|scf\\|\\(?:vc-\\)?relax\\).*\\.in\\'" . pw-mode))
\end{verbatim}
}
% 
\noindent
If we want that emacs opens \texttt{*.pwtk} files in the PWTK QE mode,
we can use:
\begin{flushleft}
{\color{red}
\verb+   ;; automatically open the *.pwtk files with the PWTK mode+}\\
\verb+   (add-to-list 'auto-mode-alist  '("\\.pwtk\\'" . pwtk-mode))+\\[1em]
\end{flushleft}

Once the package is installed according to the above instructions, we
are ready to use it. Let us, for the sake of example, open an existing
\texttt{pw.x} input file whose name does not match the above specified
filename pattern for the \pwmode. In such cases we can load the mode
with \efn{M-x pw-mode} command and we will get the content of the file
highlighted as in Figure~\ref{fig:example}.

\section{Usage}

\subsection{Available modes defined by \qemodes}

The \QEmodes\ package contains a generic \qemode\ and the following
specific modes: \pwmode, \nebmode, \cpmode, \phmode, \ldmode, and \ppmode.
%\subsubsection{Difference between generic \qemode\ and specific modes}
The difference between them is only in the extent of the syntax
highlighting and auto-indentation. Namely, these modes recognize and
highlight namelists (and their variables) and cards (and their
options/flags) that they know about.
%
The generic \qemode\ is aware of all of them for all those \qe\
programs that have explicit documentation in the form of
\verb+INPUT_+\var{PROG}\verb+.html+ files (where \var{PROG}
typically stands for the uppercase name of the program). In contrast,
a given specific mode is aware only of namelists, variables, cards, and
options of the corresponding program.

\begin{figure}[htb]
  \centering
  \includegraphics[width=0.8\textwidth]{insert-template.png}
  \caption{The result of executing the \efn{M-x pp-insert-template}
    command, which insert a template for the \ppx\ input file into the
    current buffer.}
  \label{fig:insert-template}
\end{figure}
\subsection{Commands}

The \QEmodes\ package provides the following commands:
\begin{description}
\item[$\bullet$ \efn{M-X \var{mode}-mode}]\hfill\\ toggles
  the respective mode, where \var{mode} is one of \texttt{qe},
  \texttt{pw}, \texttt{neb}, \texttt{cp}, \texttt{ph}, \texttt{ld1}, or \texttt{pp}

\item[$\bullet$ \efn{M-x indent-region}] ~~{\rm or}~~ \efn{C-M-\textbackslash}\hfill\\
  indents region according to \qemodes\ rules, i.e., namelist and card
  names are left aligned to the first column, while their content is
  indented by \texttt{qe-indent} spaces to the right (see
  Figure~\ref{fig:example}; default value of \texttt{qe-indent} is 3)

\item[$\bullet$ \efn{M-x \var{prog}-insert-template}]\hfill\\
  inserts a respective input file template (see Figure 2); this
  command may not be defined for all the \var{prog}s; currently
  supported \var{prog}s are: \texttt{pw}, \texttt{cp}, \texttt{pp},
  \texttt{neb}, \texttt{ph}, \texttt{dynmat}, \texttt{ld1},
  \texttt{projwfc}, \texttt{dos}, and \texttt{bands}.

\item[$\bullet$ \efn{M-x \var{prog-NAMELIST}}]\hfill\\ 
  inserts a blank namelist section named \var{NAMELIST}

\item[$\bullet$ \efn{M-x \var{prog-CARD}}]\hfill\\
  inserts a blank card section named \var{CARD}; the value of the
  card's \var{flag} can be selected from the provided list by using
  the right/left arrow keys

\item[$\bullet$ \efn{M-x \var{prog-variable}}]\hfill\\
  inserts a namelist variable named \var{variable}

\end{description}
The above italicized words have the following meaning:
\begin{itemize}
\item \var{prog} stands for the lowercase name of respective program
  without the \texttt{.x} suffix (i.e.\ it is the lowercase variant of
  the \var{PROG} in the respective \texttt{INPUT\_\var{PROG}.html}
  filename)
\item \var{NAMELIST} is the uppercase name for a given Fortran namelist
\item \var{CARD} is the uppercase name for a given card
\item \var{variable} is the lowercase name for a given namelist' variable
\end{itemize}
Note that in the above commands the spelling of namelist and card
names (\var{NAMELIST} and \var{CARD}) are intentionally made uppercase
as to differentiate them from the names of variables which are
intentionally made lowercase.\footnote{Note that in \qe\ the namelist
  and variable names are case-insensitive, while card names are
  case-sensitive.}

\subsection{Auto-completion mechanism}
It may at first seem that the above described commands are not a big
deal. But given that \qe\ contains hundreds of variables it is
difficult to remember the precise spelling for all of them. It is here
where these commands becomes useful due to Emacs auto-completion
mechanism. For example, typing a space or tab after \texttt{M-x pw-C} 
prints all the namelists and cards that starts with letter ``C'', i.e.:
\begin{verbatim}
   Possible completions are:
   pw-CELL                              pw-CELL_PARAMETERS
   pw-CONSTRAINTS                       pw-CONTROL
\end{verbatim}
\noindent whereas typing a space or tab after \texttt{M-x pw-c}
prints all the \pwx\ variables that starts with letter ``c'', i.e.:
\begin{verbatim}
   Possible completions are:
   pw-c                                 pw-calculation
   pw-cell_dofree                       pw-cell_dynamics
   pw-cell_factor                       pw-celldm
   pw-constrained_magnetization         pw-conv_thr
   pw-conv_thr_init                     pw-conv_thr_multi
   pw-cosab                             pw-cosac
   pw-cosbc
\end{verbatim}
\noindent
From this list we can see that there is only one variable that starts
with ``ca'', hence typing \texttt{M-x pw-ca[space][return]}, where
\texttt{[space][return]} stands for space and return keys, prints at
the point position of the current buffer:
\begin{verbatim}
   calculation = ''
\end{verbatim}

\subsubsection{Selection of card's flag value}

Another available completion is the selection of the card's flag
value. For example, by typing:
\begin{verbatim}
   M-x pw-K\_P[space][enter]
\end{verbatim}
the following list of possible values for the \verb+K_POINTS+'s flag
appears:
\begin{flushleft}
~~~\texttt{Select the flag: \{}\textbf{tpiba}\texttt{ | automatic |
  crystal | gamma | ...\}}.
\end{flushleft}
The currently active value is written in
bold; to use it press \texttt{[enter]}, whereas to select another
value use the right ($\rightarrow$) or left ($\leftarrow$) arrow keys.

\subsection{Controlling indentation}

The basic indentation offset in \qemodes\ is 3. It is controlled by
\texttt{qe-indent} variable. Hence if you want to change it, add the
following into your \texttt{user-init-file}
(e.g. \texttt{\$HOME/.emacs}):
\begin{flushleft}
\verb+   (setq qe-indent +\var{myOffset}\verb+)+
\end{flushleft}
where \var{myOffset} is the integer value of the offset of your
choice. For no indentation, set the \texttt{qe-indent} to 0 (this
implies that auto-indentation will make all lines non-indented).

To disable the auto-indentation for a given mode (are you really sure
you want to do this), add the following into your
\texttt{user-init-file}:

{\small
\begin{flushleft}
\verb+   (add-hook '+\var{mode}\verb+-mode (lambda () (setq indent-line-function 'indent-relative)))+
\end{flushleft}
}

\noindent where \var{mode} is \texttt{qe}, \texttt{pw}, \texttt{neb}, \texttt{cp},
\texttt{ph}, \texttt{ld1}, or \texttt{pp}.

\subsection{Note to \texttt{Vi} users}

A simple way to get a \QEmodes\ aware \texttt{Vi}-compatible editor is
to use the \texttt{Evil} package -- an \textbf{e}xtensible \textbf{vi}
\textbf{l}ayer for Emacs
(\texttt{https://bitbucket.org/lyro/evil/wiki/Home}). With the
\texttt{Evil} mode enabled, Emacs will behave like the \texttt{Vi}
editor, but with the \QEmodes\ support.

\end{document}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End:
