*gentoo-syntax.txt*	Gentoo Syntax Plugin

Authors:  Ciaran McCreesh <ciaranm   at gentoo dot org>
          Aaron Walker    <ka0ttic   at gentoo dot org>
          Tom Martin      <slarti    at gentoo dot org>
          Elfyn McBratney <beu       at gentoo dot org>
          Mike Kelly      <pioto     at gentoo dot org>
          Tim Harder      <radhermit at gentoo dot org>

==============================================================================
1. Contents						       *gentoo-syntax*

    1. Contents                                            |gentoo-syntax|

    2. Plugin Information                         |gentoo-syntax-overview|
	Detection Specifics                      |gentoo-syntax-detection|
	Highlighting Specifics                |gentoo-syntax-highlighting|
	    Common Syntax Rules                     |gentoo-common-syntax|
	    Ebuild and Eclass Files                 |gentoo-ebuild-syntax|
	    GLEP Files                                |gentoo-glep-syntax|
	    ChangeLogs                           |gentoo-changelog-syntax|
	    conf.d Files                            |gentoo-conf.d-syntax|
	    cron.d Files                            |gentoo-cron.d-syntax|
	    env.d Files                              |gentoo-env.d-syntax|
	    GuideXML Syntax                       |gentoo-guidexml-syntax|
	    init.d Files                            |gentoo-init.d-syntax|
	    make.conf Files                      |gentoo-make-conf-syntax|
	    metadata.xml Files                    |gentoo-metadata-syntax|
	    package.(un)mask                  |gentoo-package-mask-syntax|
	    package.keywords              |gentoo-package-keywords-syntax|
	    package.use                        |gentoo-package-use-syntax|
	    thirdpartymirrors                      |gentoo-mirrors-syntax|
	    use.desc, use.local.desc              |gentoo-use-desc-syntax|
	Settings Specifics                        |gentoo-syntax-settings|
	Indent Specifics                          |gentoo-indent-settings|
	New conf.d Files                                      |new-conf.d|
	New Ebuilds                                          |new-ebuilds|
	New init.d Files                                      |new-init.d|
	New Metadata                                        |new-metadata|

==============================================================================
2. Plugin Information				      *gentoo-syntax-overview*

	The gentoo-syntax package provides a collection of syntax, ftdetect,
	ftplugin and indent files to help Gentoo developers and users work
	with ebuilds, eclasses, GLEPs, Gentoo style ChangeLogs, init.d /
	conf.d / env.d / cron.d entries, /etc/portage/ files and so on.

    Detection Specifics				     *gentoo-syntax-detection*

	Ebuilds are detected by an 'ebuild' extension. Eclasses are detected
	by an 'eclass' extension. Both ebuild and eclass files are assigned
	the 'ebuild' filetype.

	GLEP files are detected by a 'txt' extension, followed by a check that
	the first line of the file starts with "GLEP: ". They are assigned the
	'glep' filetype.

	Gentoo ChangeLogs are detected by the 'ChangeLog' filename and a
	copyright header on the second line.

	init.d scripts are detected by being in /etc/init.d/ . They are also
	detected if they are under a files/ directory and include a
	'#!/sbin/runscript' header.

	conf.d, env.d and cron.d files are detected by being in the relevant
	subdirectory in /etc.

	package.mask, package.unmask, package.keywords, package.use and
	thirdpartymirrors files are detected by filename.

	make.conf files are detected by filename (make.globals is also
	recognised).

	metadata.xml files are detected by filename.

	use.desc files are detected by filename (use.local.desc is also
	recognised).

    Highlighting Specifics			  *gentoo-syntax-highlighting*

	Syntax highlighting is provided for ebuild/eclass, GLEP files,
	Gentoo ChangeLogs and init.d / conf.d / env.d / cron.d scripts.

							*gentoo-common-syntax*

	Many of the syntax files are based upon gentoo-common.vim, which
	provides basic syntax highlighting for header blocks and bug numbers.

							*gentoo-ebuild-syntax*

	The ebuild/eclass syntax file builds upon the vim-provided |sh.vim|
	and adds in highlighting for:
	    * ebuild.sh / portage keywords
	    * functions from commonly used eclasses (eutils, flag-o-matic,
	      gcc, libtool, fixheadtails, webapp, webapp-apache, versionator,
	      cvs, fdo-mime, multilib, 64-bit, cron, games, toolchain-funcs,
	      subversion, alternatives, rpm, python, check-kernel,
	      perl-module, distutils)
	    * common mistakes (assigning to read-only variables, misspellings,
	      leading non-tab spaces, default WORKDIR assignment)

							  *gentoo-glep-syntax*

	Syntax highlighting for GLEP files is based upon the vim-provided rst
	syntax file. Additional highlighting is available for the headers at
	the top of the file and for heading sections.

						     *gentoo-changelog-syntax*

	Syntax highlighting for Gentoo ChangeLogs is implemented from scratch
	(some rules come from |gentoo-common-syntax|).

							*gentoo-conf.d-syntax*

	Syntax highlighting for conf.d files is based upon the vim-provided
	|sh.vim|, with additional support for certain Gentooisms (some rules
	come from |gentoo-common-syntax|).

							*gentoo-cron.d-syntax*

	Syntax highlighting for cron.d entries uses the vim-provided
	crontab.vim file.

							 *gentoo-env.d-syntax*

	Syntax highlighting for env.d files is based upon the vim-provided
	|sh.vim|, with additional support for certain Gentooisms (some rules
	come from |gentoo-common-syntax|).

						      *gentoo-guidexml-syntax*

	Syntax highlighting for guidexml files is based upon the vim-provided
	|xml.vim|.

							*gentoo-init.d-syntax*

	Syntax highlighting for init.d files is based upon the vim-provided
	|sh.vim|, with additional support for certain Gentooisms (some rules
	come from |gentoo-common-syntax|).

						     *gentoo-make-conf-syntax*

	Syntax highlighting for make.conf files is implemented from scratch
	(some rules come from |gentoo-common-syntax|).

						     *gentoo-metadata-syntax*

	Syntax highlighting for metadata.xml files is based upon the
	vim-provided |xml.vim|, with additional highlighting for recognised
	elements.

						  *gentoo-package-mask-syntax*

	Syntax highlighting for package.mask and package.unmask files is
	implemented from scratch (some rules come from
	|gentoo-common-syntax|).

					      *gentoo-package-keywords-syntax*

	Syntax highlighting for package.keywords files is implemented from
	scratch (some rules come from |gentoo-common-syntax|).

						   *gentoo-package-use-syntax*

	Syntax highlighting for package.use files is implemented from scratch
	(some rules come from |gentoo-common-syntax|).

						       *gentoo-mirrors-syntax*

	Syntax highlighting for thirdpartymirrors files is implemented from
	scratch (some rules come from |gentoo-common-syntax|).

						      *gentoo-use-desc-syntax*
	Syntax highlighting for use.desc and use.local.desc is implemented
	from scratch (some rules come from |gentoo-common-syntax|).

    Settings Specifics				      *gentoo-syntax-settings*

	For ebuilds and eclasses, tabs (|'shiftwidth'| and |'tabstop'|) are set
	to four spaces and tab to space conversion (|'expandtab'|) is disabled.
	To allow proper syntax highlighting for commands like 'strip-flags',
	the hyphen character is added as a valid keyword character
	(|'iskeyword'|).

	For ebuilds, eclasses and ChangeLogs, UTF-8 is used for fileencoding
	as per GLEP 31.

    Indent Specifics				      *gentoo-indent-settings*

	Indent settings for ebuilds and eclasses are the same as for regular
	bash files.

    New conf.d Files				      *new-conf.d* *:NewConfd*

	New conf.d files will automatically have a skeleton content created
	for them.

	The ':NewConfd' command can be used to manually create contents for a
	new conf.d file.

	Note: conf.d files may not be detected automatically. The |:NewConfd|
	command will still work in these situations.

    New Ebuilds					    *new-ebuilds* *:NewEbuild*

	New ebuilds will automatically have content placed into them based
	upon context (for example, the package category). Similarly, new
	eclasses are created from a template. If the environment variable
	'ECHANGELOG_USER' is set, it will be used for the author's name.
	Otherwise, the 'USER' environment variable will be used.

	The ':NewEbuild' command can be used to manually create contents for a
	new ebuild or eclass file.

	To disable the autogenerate functionality place into your .vimrc file:

	    let g:ebuild_create_on_empty = 0

    New init.d Files				      *new-init.d* *:NewInitd*

	New init.d files will automatically have a skeleton content created
	for them.

	The ':NewInitd' command can be used to manually create contents for a
	new init.d file.

	Note: init.d files may not be detected automatically. The |:NewInitd|
	command will still work in these situations.

    New Metadata				 *new-metadata* *:NewMetadata*

	New metadata.xml files will automatically have content placed into
	them based upon context (for example, the package category). If the
	environment variable 'ECHANGELOG_USER' is set, it will be used for the
	author's name and email address.

	The ':NewMetadata' command can be used to manually create contents for
	a new metadata file.

	Note: metadata.xml files may not be detected automatically. The
	|:NewMetadata| command will still work in these situations.

vim:tw=78:ts=8:ft=help
