\input texinfo   @c -*-texinfo-*-
@comment %**start of header
@setfilename graphviz-dot-mode.info
@comment created under Texinfo 6.4
@set PACKAGE @code{graphviz-dot-mode}
@set AUTHOR Pieter Pareit
@set VERSION 0.3.10
@set RELEASED 25 May 2015
@set SWCYEARS 2002-2015
@set PACURL @uref{http://ppareit.github.io/graphviz-dot-mode/}
@set SRCURL @uref{https://github.com/ppareit/graphviz-dot-mode}
@set PACSRC @code{graphviz-dot-mode.el}

@set TITLE @value{PACKAGE} Manual
@settitle @value{TITLE}
@set DESCRIPTION This manual describes how to install and use @value{PACKAGE}, an Emacs package for working with @cite{Graphviz} DOT-format files.
@documentdescription
@value{DESCRIPTION}
@end documentdescription
@set EDITION @value{VERSION}.a
@set EDITOR Daniel Birket
@set DOCURL @uref{https://github.com/daniel-birket/graphviz-dot-mode}

@set TEXINFO @cite{@acronym{GNU} Texinfo v6.4}
@set EMACS @cite{Emacs v25.2.1}
@set PANDOC @cite{Pandoc v1.19.2.1}
@comment %**end of header
@syncodeindex vr fn
@syncodeindex ky cp

@copying
@cindex copyright (manual)
Copyright @copyright{} 2018 @value{EDITOR}.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the @acronym{GNU} Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with no Front-Cover Texts, and
with no Back-Cover Texts.  A copy of the license is included in the
section entitled @cite{@acronym{GNU} Free Documentation License}.
@end quotation

This is the @cite{@value{TITLE}}, edition @value{EDITION}, by
@value{EDITOR}, updated @today{}, which describes how to install and
use the Emacs package @value{PACKAGE}, version @value{VERSION},
released @value{RELEASED}, which was written by and Copyright
@copyright{} @value{SWCYEARS} @value{AUTHOR}, et al@.  (See
@value{PACURL})

@ifinfo
This @command{info}
@end ifinfo
@iftex
This typeset
@end iftex
@ifhtml
This @acronym{HTML}
@end ifhtml
@ifdocbook
This
@end ifdocbook
document was composed using @value{EMACS} (Richard
M. Stallman, et al.  See @uref{https://www.gnu.org/software/emacs/})
and compiled from @file{.texi} source with @value{TEXINFO} (Richard
M. Stallman, et al.  See @uref{https://www.gnu.org/software/texinfo/})
@iftex
and typeset using @TeX{} (Donald Knuth, et al.  See
@uref{https://www.gnu.org/software/texinfo/})
@end iftex
@ifdocbook
to @command{docbook} format (@acronym{OASIS} See @uref{http://docbook.org}, then
converted to this format using @value{PANDOC} (John MacFarlane, et
al@. @uref{http://pandoc.org})  This format has no index.
@end ifdocbook
@cite{Graphviz} is by @acronym{AT&T} Labs Research.  (See @uref{http://graphviz.org})
@end copying

@dircategory Emacs editing modes
@direntry
* Graphviz DOT mode: (graphviz-dot-mode).       Emacs mode for Graphviz format.
@end direntry

@titlepage
@title @value{TITLE}
@subtitle edition @value{EDITION}
@subtitle for @value{PACKAGE} version @value{VERSION}
@author @value{PACKAGE} by @value{AUTHOR}, et al.
@author manual by @value{EDITOR}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnotdocbook
@ifnottex
@node Top
@top @value{TITLE}
@value{DESCRIPTION}

@ifinfo
In @command{info}, type @kbd{3} to jump to the chapter on using
@value{PACKAGE}.
@end ifinfo

@insertcopying
@end ifnottex
@end ifnotdocbook

This manual is based upon the comments and doc strings in the
@value{PACSRC} source code, which begins with:

@cindex copyright (software)
@lisp
;;; graphviz-dot-mode.el --- Mode for the dot-language used by graphviz (att).

;; Copyright (C) 2002 - 2015 Pieter Pareit <pieter.pareit@@gmail.com>

;; This program is free software; you can redistribute it and/or
;; modify it under the terms of the GNU General Public License as
;; published by the Free Software Foundation; either version 2 of
;; the License, or (at your option) any later version.

;; This program is distributed in the hope that it will be
;; useful, but WITHOUT ANY WARRANTY; without even the implied
;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
;; PURPOSE.  See the GNU General Public License for more details.
@dots{}

;; Authors: Pieter Pareit <pieter.pareit@@gmail.com>
;;          Rubens Ramos <rubensr AT users.sourceforge.net>
;;          Eric Anderson http://www.ece.cmu.edu/~andersoe/
;; Maintainer: Pieter Pareit <pieter.pareit@@gmail.com>
;; Homepage: https://ppareit.github.io/graphviz-dot-mode/
;; Created: 28 Oct 2002
;; Last modified: 25 May 2015
;; Version: 0.3.10
;; Keywords: mode dot dot-language dotlanguage graphviz graphs att
@end lisp

@menu
* Introduction::                About @cite{Graphviz} and @value{PACKAGE}.
* Installing::                  How to Get and Install @value{PACKAGE}.
* Using @value{PACKAGE}::       How to Use @value{PACKAGE}
* Customizing::                 How to customize @value{PACKAGE}.
* Credits::
* @acronym{GNU} General Public License 2.0::  License of @value{PACKAGE}.
* @acronym{GNU} Free Documentation License::  License of this document.
* Functions & Variables::
* Keys and Concepts::
@end menu

@node Introduction
@chapter Introduction
@cindex introduction
@value{DESCRIPTION}
The features of this package help you to create @file{.dot} or
@file{.gv} files containing syntax compatible with the separate
@cite{Graphviz} package and use @cite{Graphviz} to convert these files
to diagrams.

@pindex Graphviz
@cindex graph
@cindex node
@cindex edge
@cite{Graphviz} is a set of open source graph visualization tools
created by @acronym{AT&T} Labs Research.  A @dfn{graph} is a way of
representing information as a network of connected @dfn{nodes} (shapes) and
@dfn{edges} (lines). @cite{Graphviz} is documented at
@uref{http://graphviz.org}.

@pindex Emacs
The powerful text editor, Emacs, was created in 1976 by Richard
Stallman.  It is highly customizable and has 40 years of other
extensions.  @cite{@acronym{GNU} Emacs} is documented at
@uref{https://www.gnu.org/software/emacs/}. @cite{XEmacs} is
documented at @uref{http://www.xemacs.org}.

@node Installing
@chapter Installing
@cindex installing
This chapter describes how to install @value{PACKAGE}.

@menu
* Recommended Installation::    Install the easy way.
* Installing by Hand::          Install the hard way.
* Installing this Info Manual:: How to Install this @command{info} manual.
@end menu

@node Recommended Installation
@section Recommended Installation
@cindex recommended installation
@cindex installation, the easy way
@cindex @code{package.el}, installing with
@cindex MELPA Stable, installing from
The recommended way to install the package @value{PACKAGE} is to
use @code{package.el} and @kbd{M-x package-install}.

@vindex package-archives
@findex package-initialize
To install @value{PACKAGE}, first add the MELPA Stable archive to the
list of archives used by @code{package.el} (if it is not already there)
by adding the following lines to your @file{.emacs} or other Emacs
startup file. Then restart Emacs.

@lisp
(require 'package)
(add-to-list 'package-archives
             '("melpa-stable" . "https://stable.melpa.org/packages/"))
             
(package-initialize)
@end lisp

(For more detailed and comprehensive instructions about using MELPA,
please see @uref{https://melpa.org/#/getting-started}.)

@findex package-install
After restarting Emacs, type the following to install @value{PACKAGE}.

@kbd{M-x package-install @key{RET} graphviz-dot-mode @key{RET}}.

When installed this way using the package manager, @value{PACKAGE}
will be activated automatically for file names ending in either @file{.dot}
or @file{.gv}.

@node Installing by Hand
@section Installing by Hand
@cindex installing by hand
@cindex installation, the hard way
You can manually download and install @value{PACKAGE}, but it is best
to use the recommended method above if you don't already know how to
manually install an Emacs program.

You may download @file{graphviz-dot-mode.el} from@*@value{PACURL} and
follow the instructions that you find there.

@node Installing this Info Manual
@section Installing this Info Manual
@cindex Installing this Info Manual
This section describes how to install this manual so that it may be
used from within Emacs using its @code{info} reader.
@enumerate
@item Obtain the file containing the info-format version of this manual, @file{graphviz-dot-mode.info.gz} (See @value{DOCURL}.)
@item In Emacs, use @kbd{C-h v Info-directory-list@key{RET}} to display the contents of the @code{Info-directory-list} variable. (This may be the same as the @env{INFOPATH} environment variable.)
@item Copy the @file{graphviz-dot-mode.info.gz} file to one of the directories in the @code{Info-directory-list} variable.
@item Use @command{install-info} to add an entry for the new @file{graphviz-dot-mode.info.gz} file into the @file{dir} file in the info directory where you copied the file.
@item In Emacs, use @kbd{C-h i d m graphviz-dot-mode @key{RET}} to display this help file.
@end enumerate

The @file{Makefile} in the @file{texinfo} subdirectory of the GitHub archive at @value{DOCURL} includes an option to install the info file with @command{make install}. You must first modify the variables in the top of the Makefile to use the correct directories and files for your system.

You must install @value{TEXINFO} to use @command{install-info} or the @file{Makefile}.
@node Using @value{PACKAGE}
@chapter Using @value{PACKAGE}
@cindex using
This chapter describes how to use @value{PACKAGE}.

@menu
* Compiling & Viewing::         How to use Compile and View Functions.
* Editing::                     How to edit.
@end menu

@node Compiling & Viewing
@section Compiling & Viewing
@cindex compiling
@cindex viewing
This section describes how to use compile and view
functions. @xref{Compile & View Variables}.

@table @asis
@item @kbd{C-c c} (@code{compile})
@kindex @kbd{C-c c}
@findex compile
This command compiles the current dot file visited by the @cite{Emacs}
buffer. The output file is in the same directory and has the extension
determined by the variable @code{graphviz-dot-preview-extension}.

@item @kbd{C-x `} (@code{next-error})
@kindex @kbd{C-x `}
@findex next-error
This command will jump to the location in the source file of the next
error from the most recent compile. Use @kbd{C-c c} to compile first.

@item @kbd{C-c p} (@code{graphviz-dot-preview})
@kindex @kbd{C-c p}
@findex graphviz-dot-preview
@cindex preview
@vindex image-file-name-extensions
@vindex image-formats-alist
This command compiles and then (if it compiled successfully) shows the
output of the current dot file visited by the @cite{Emacs} buffer,
provided that @cite{@acronym{GNU} Emacs} or @cite{XEmacs} is running
on a graphical display capable of displaying the graphic file output
by @command{dot}.

See @code{image-file-name-extensions} in @cite{@acronym{GNU} Emacs} or
@code{image-formats-alist} in @cite{XEmacs} to customize the graphic
files that can be displayed.

@item @kbd{C-c v} (@code{graphviz-dot-view})
@kindex @kbd{C-c v}
@findex graphviz-dot-view
@cindex external viewer
@vindex graphviz-dot-view-edit-command
@vindex graphviz-dot-save-before-view
This command invokes an external viewer specified by the variable
@code{graphviz-dot-view-command}. If
@code{graphviz-dot-view-edit-command} is @code{t}, you will be
prompted to enter a new @code{graphviz-dot-view-command}. If
@code{graphviz-dot-save-before-view} is @code{t}, the buffer is saved
before the external viewer command is invoked.

(See @uref{http://graphviz.org/content/resources} for a
list of @cite{Graphviz} viewers and editors.)
@end table

@node Editing
@section Editing
@cindex editing
This section describes how to edit with @value{PACKAGE}.
@xref{Editing Variables}.
@menu
* Indenting::   How to use Indenting commands
* Completion::  How to use Completion command
* Commenting::  How to use Commenting commands
@end menu

@node Indenting
@subsection Indenting
@cindex indenting
@table @asis
@item @kbd{C-M-q} (@code{graphviz-dot-indent-graph})
@kindex @kbd{C-M-q}
@findex graphviz-dot-indent-graph
This command will indent the graph, diagraph, or subgraph at point and
any subgraph within it.

@item @kbd{@key{TAB}}
@kindex @kbd{@key{TAB}}
This key will automatically indent the line. It does not perform completion.

@item @kbd{M-j} (@code{comment-indent-newline})
@xref{Commenting}

@item @kbd{@key{RET}} (@code{electric-graphviz-dot-terminate-line})
@kindex @kbd{@key{RET}}
@findex electric-graphviz-dot-terminate-line
If the variable @code{graphviz-dot-auto-indent-on-newline} is
@code{t}, @kbd{@key{RET}} will insert a newline and indent the next line.

@item @kbd{@{} (@code{electric-graphviz-dot-open-brace})
@kindex @kbd{@{}
@findex electric-graphviz-dot-open-brace
If the variable @code{graphviz-dot-auto-indent-on-braces} is
@code{t}, @kbd{@{} will insert a @kbd{@{}, newline and indent the next line.

@item @kbd{@}} (@code{electric-graphviz-dot-close-brace})
@kindex @kbd{@}}
@findex electric-graphviz-dot-close-brace
If the variable @code{graphviz-dot-auto-indent-on-braces} is
@code{t}, @kbd{@}} will insert a @kbd{@}}, newline and indent the next line.

@item @kbd{;} (@code{electric-graphviz-dot-semi})
@kindex @kbd{;}
@findex electric-graphviz-dot-semi
If the variable @code{graphviz-dot-auto-indent-on-semi} is
@code{t}, @kbd{;} will insert a @kbd{;}, newline and indent the next line.
@end table

@node Completion
@subsection Completion
@table @asis
@item @kbd{M-t} (@code{graphviz-dot-complete-word})
@kindex @kbd{M-t}
@findex graphviz-dot-complete-word
This command will complete the attribute or value keyword at point. If
more than one completion is possible, a list is displayed in the
minbuffer.
@end table

@xref{Completion Variables}

@node Commenting
@subsection Commenting
@cindex commenting

@table @asis
@item @kbd{M-;} (@code{comment-dwim})
@kindex @kbd{M-;}
@findex comment-dwim
This command will perform the comment command you want (Do What I
Mean).  If the region is active and @code{transient-mark-mode} is on, it
will comment the region, unless it only consists of comments, in which
case it will un-comment the region.  Else, if the current line is
empty, it will insert a blank comment line,
otherwise it will append a comment to the line and indent it.

@kindex C-u M-;
Use @kbd{C-u M-;} to kill the comment on the current line.

@item @kbd{C-x C-;} (@code{comment-line})
@kindex C-x C-;
@findex comment-line
This command will comment or un-comment the current line.

@item @kbd{M-j} (@code{comment-indent-newline})
@kindex @kbd{M-j}
@findex comment-indent-newline
This command will break line the at point and indent, continuing a
comment if within one.  This indents the body of the continued comment
under the previous comment line.

@item @kbd{C-c C-c} (@code{comment-region})
@kindex @kbd{C-c C-c}
@findex comment-region
This command will comment-out the region.

You may also use @kbd{M-;} (@code{comment-dwin}) to comment the region
if @code{transient-mark-mode} is on.

@item @kbd{C-c C-u} (@code{graphviz-dot-uncomment-region})
@kindex @kbd{C-c C-u}
@findex graphviz-dot-uncomment-region
This command will un-comment the region.

You may also use @kbd{C-u M-;} (@code{comment-dwin}) to un-comment the region
if @code{transient-mark-mode} is on.
@end table

@node Customizing
@chapter Customizing
@cindex customizing
This section describes the customizable variables of @value{PACKAGE}.
You may customize variables by typing

@table @kbd
@item M-x graphviz-dot-customize @key{RET}
@kindex M-x graphviz-dot-customize @key{RET}
@findex graphviz-dot-customize
This function invokes the Emacs customization facility to allow you to
view and change the @value{PACKAGE} variables below.
@end table

@menu
* Compile & View Variables::    How to customize Compile & View Functions.
* Editing Variables::           How to customize Editing Functions.
* Keyword Variables::           Keyword Customizations.
* Mode Hook::                   The mode hook variable.
@end menu

@node Compile & View Variables
@section Compile & View Variables
@cindex variables, compile
@cindex variables, view
This section describes variables related to compiling and viewing.
@xref{Compiling & Viewing}

@vtable @code
@item graphviz-dot-dot-program
@kindex @kbd{C-c c}
@findex compile
string, default: ``dot''

This variable determines the command name (and path, if necessary)
used to invoke the @cite{Graphviz} @command{dot} program. The @kbd{C-c
c} (@code{compile}) function invokes this command.

@item graphviz-dot-preview-extension
@findex compile
@kindex @kbd{C-c p}
@findex graphviz-dot-preview
string, default ``png''

This variable determines the file extension used for the @kbd{C-c c}
(@code{compile}) and @kbd{C-c p} (@code{graphviz-dot-preview})
functions. The format for the compile command is

@command{dot -T<extension> <filename>.dot > <filename>.<extension>}

@item graphviz-dot-save-before-view
@kindex @kbd{C-c v}
@findex graphviz-dot-view
boolean, default @code{t}

This variable controls whether the buffer will be saved to the visited file
before the @kbd{C-c v} (@code{graphviz-dot-view}) function invokes the
external dot-file viewer command. Set this boolean variable to
@code{t} (true) or @code{nil} (false).

@item graphviz-dot-view-command
@kindex @kbd{C-c v}
@findex graphviz-dot-view
string, default: ``doted %s''

This variable determines the command name (and path, if necessary)
used to invoke an external dot-file viewer program. The @kbd{C-c v}
(@code{graphviz-dot-view}) function invokes this command. The name of
the file visited by the buffer will be substituted for @code{%s} in
this string.

(See @uref{http://graphviz.org/content/resources} for a
list of @cite{Graphviz} viewers and editors.)

@item graphviz-dot-view-edit-command
@kindex @kbd{C-c v}
@findex graphviz-dot-view
@vindex graphviz-dot-view-command
boolean, default: @code{nil}

This variable controls whether you will be prompted for the external dot-file
viewer command name when you use @kbd{C-c v}
@code{graphviz-dot-view}. Set this to @code{t} (true) to be prompted
to edit the viewer command variable @code{graphviz-dot-view-command}
every time you use @kbd{C-c v} or @code{nil} to avoid the prompt.

@end vtable

@node Editing Variables
@section Editing Variables
@cindex variables, editing
This section describes variables related to editing.
@xref{Editing}

@menu
* Indenting Variables::         Variables about Indenting.
* Completion Variables::        Variables about Completion.
@end menu

@node Indenting Variables
@subsection Indenting Variables
@cindex variables, indenting
This subsection describes variables related to indenting.

@vtable @code
@item graphviz-dot-auto-indent-on-braces
@kbd{@{}
@findex electric-graphviz-dot-open-brace
@kbd{@}}
@findex electric-graphviz-dot-close-brace
boolean, default @code{nil}

This variable controls whether the functions
@code{electric-graphviz-dot-open-brace} and
@code{electric-graphviz-dot-close-brace} are called when @kbd{@{} and
@kbd{@}} are typed. Set this boolean variable to @code{t} (true) or
@code{nil} (false).

@item graphviz-dot-auto-indent-on-newline
@kindex @kbd{@key{RET}}
@findex electric-graphviz-dot-terminate-line
boolean, default @code{t}

This variable controls whether the function
@code{electric-graphviz-dot-terminate-line} is called when a line is
terminated with a newline. Set this boolean variable to @code{t}
(true) or @code{nil} (false).

@item graphviz-dot-auto-indent-on-semi
@kindex @kbd{;}
@findex electric-graphviz-dot-semi
boolean, default @code{t}

This variable controls whether the function @code{electric-graphviz-dot-semi}
is called when a semicolon @kbd{;} is typed. Set this boolean variable
to @code{t} (true) or @code{nil} (false).

@item graphviz-dot-indent-width
@vindex standard-indent
integer, default: @code{standard-indent}

This variable determines the indentation used in @value{PACKAGE} buffers.

@end vtable

@node Completion Variables
@subsection Completion Variables
@cindex variables, completion
This subsection describes variables related to completion.

@vtable @code
@item graphviz-dot-delete-completions
boolean, default: @code{nil}

This variable controls whether the completion buffer is automatically
deleted when a key is pressed. Set this boolean variable to @code{t}
(true) or @code{nil} (false).

@item graphviz-dot-toggle-completions
@kindex @kbd{M-t}
@findex graphviz-dot-complete-word
boolean, default: @code{nil}

This variable controls whether repeated use of @kbd{M-t}
@code{graphviz-dot-complete-word} will toggle the display of possible
completions in the minibuffer. If this variable is set to @code{nil},
when there are more than one possible completions, a buffer will display
all completions. Set this boolean variable to @code{t} (true) or
@code{nil} (false).

@end vtable

@node Keyword Variables
@section Keyword Variables
@cindex variables, keyword
This section describes the variables containing DOT-language keywords,
which may change if @cite{Graphviz} is updated. You may update these
variables after new releases of @cite{Graphviz}from
@uref{http://www.graphviz.org/doc/schema/attributes.xml} .

@vtable @code
@item graphviz-dot-attr-keywords
list of strings, default: (``graph'' ``digraph'' @dots{} )

This variable holds a list of keywords for attribute names in a
graph. This is used by the @kbd{M-t} auto completion function. The
actual completion tables are built when the mode is loaded, so changes
to this variable are not immediately visible.

@item graphviz-dot-value-keywords
list of strings, default: (``true'' ``false'' @dots{} )

This variable holds a list of keywords for attribute values in a
graph. This is used by the @kbd{M-t} auto completion function. The
actual completion tables are built when the mode is loaded, so changes
to this variable are not immediately visible.

@end vtable

@node Mode Hook
@section Mode Hook
@cindex variables, mode hook

@vtable @code
@item graphviz-dot-mode-hook
list of functions, default: @code{nil}

This variable determines which functions are called when
@value{PACKAGE} starts. To use it, add a line like below to your
@file{.emacs} or other startup file.
@lisp
(add-hook 'graphviz-dot-mode-hook 'my-hook)
@end lisp
@end vtable

@node Credits
@chapter Credits
@cindex credits
@value{PACKAGE} was written by:
@itemize
@item Pieter Pareit @email{pieter.pareit@@gmail.com}
@item Rubens Ramos @email{rubensr@@users.sourceforge.net}
@item Eric Anderson @uref{http://www.ece.cmu.edu/~andersoe/}
@end itemize

Other contributors are noted in the version history in the
@value{PACSRC} file and the commit history on GitHub.

The source code is maintained on GitHub at @value{SRCURL} by Pieter
Pareit (@email{pieter.pareit@@gmail.com}). Please email software
comments, suggestions and corrections there.

This manual is maintained on GitHub at @value{DOCURL} by Daniel Birket
(@email{danielb@@birket.com}). Please submit document errata to the
issue tracker there.

@node @acronym{GNU} General Public License 2.0
@unnumbered @acronym{GNU} General Public License 2.0
@cindex license (software)
@cindex @acronym{GNU} General Public License 2.0

@include gpl-2.0.texi

@c @node @acronym{GNU} General Public License 3.0
@c @unnumbered @acronym{GNU} General Public License 3.0
@c @cindex license (updated)
@c @cindex @acronym{GNU} General Public License 3.0
@c 
@c @include gpl.texi
@c 
@node @acronym{GNU} Free Documentation License
@unnumbered @acronym{GNU} Free Documentation License
@cindex license (manual)
@cindex @acronym{GNU} Free Documentation License

@include fdl.texi
@node Functions & Variables
@unnumbered Functions & Variables
@printindex fn
@node Keys and Concepts
@unnumbered Keys and Concepts
@printindex cp
@bye