Use docbooks for help
This commit is contained in:
Yevgen Muntyan
parent
c0289c3020
commit
095ab38eb0
@ -42,8 +42,10 @@ moo/moolua/moo-lua-api.cpp
|
||||
moo/moolua/gtk-lua-api.cpp
|
||||
doc/help/*
|
||||
doc/man-medit.t2t
|
||||
doc/medit.texi
|
||||
doc/medit.1
|
||||
doc/script-lua.docbook
|
||||
doc/script-lua-gtk.docbook
|
||||
doc/script-python.docbook
|
||||
doc/lgpl.no-fancy-chars
|
||||
doc/medit-defines.ent
|
||||
doc/moo-help-sections.h
|
||||
|
||||
@ -5,6 +5,10 @@ from mpi.module import *
|
||||
|
||||
tmpl_file_start = """\
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<!DOCTYPE article [
|
||||
<!ENTITY % medit-defines SYSTEM "medit-defines.ent">
|
||||
%medit-defines;
|
||||
]>
|
||||
<article>
|
||||
"""
|
||||
|
||||
@ -87,7 +91,8 @@ class Writer(object):
|
||||
text = re.sub(r'%FALSE\b', '<constant>%s</constant>' % self.constants['FALSE'], text)
|
||||
|
||||
def repl_func(m):
|
||||
return '<function><link linkend="%s" endterm="%s.title"></link></function>' % (m.group(1), m.group(1))
|
||||
return '<function><link linkend="%(mode)s.%(func_id)s" endterm="%(mode)s.%(func_id)s.title"></link></function>' % \
|
||||
dict(func_id=m.group(1), mode=self.mode)
|
||||
text = re.sub(r'([\w\d_.]+)\(\)', repl_func, text)
|
||||
|
||||
assert not re.search(r'NULL|TRUE|FALSE', text)
|
||||
@ -143,10 +148,11 @@ class Writer(object):
|
||||
oops(func_id)
|
||||
|
||||
func_id = func.c_name
|
||||
mode = self.mode
|
||||
|
||||
self.out.write("""\
|
||||
<sect2 id="%(func_id)s">
|
||||
<title id="%(func_id)s.title">%(func_name)s()</title>
|
||||
<sect2 id="%(mode)s.%(func_id)s">
|
||||
<title id="%(mode)s.%(func_id)s.title">%(func_name)s()</title>
|
||||
<programlisting>%(func_name)s(%(params_string)s)</programlisting>
|
||||
""" % locals())
|
||||
|
||||
|
||||
10
autogen.sh
10
autogen.sh
@ -4,8 +4,8 @@
|
||||
[ -z "$AUTOMAKE" ] && AUTOMAKE=automake
|
||||
|
||||
workingdir=`pwd`
|
||||
srcdir=`dirname "$0"`
|
||||
srcdir=`cd "$srcdir" && pwd`
|
||||
rel_srcdir=`dirname "$0"`
|
||||
srcdir=`cd "$rel_srcdir" && pwd`
|
||||
|
||||
cd "$srcdir"
|
||||
|
||||
@ -22,3 +22,9 @@ run_cmd $ACLOCAL --force -I m4 $ACLOCAL_FLAGS
|
||||
run_cmd $AUTOCONF --force
|
||||
run_cmd $AUTOHEADER --force
|
||||
run_cmd $AUTOMAKE --add-missing --copy --force-missing
|
||||
|
||||
if [ "$1" ]; then
|
||||
cd $workingdir && run_cmd $rel_srcdir/configure --enable-dev-mode "$@"
|
||||
else
|
||||
echo "Done. Run '$rel_srcdir/configure --enable-dev-mode' to configure"
|
||||
fi
|
||||
|
||||
110
doc/Makefile.am
110
doc/Makefile.am
@ -2,30 +2,9 @@ BUILT_SOURCES =
|
||||
|
||||
if MOO_DEV_MODE
|
||||
|
||||
# docbook_files = \
|
||||
# medit.docbook \
|
||||
# prefs.docbook
|
||||
#
|
||||
# medit.docbook: medit.docbook.in $(top_builddir)/config.status
|
||||
# $(AM_V_GEN)cd $(top_builddir) && ./config.status --silent --file=doc/medit.docbook
|
||||
# $(AM_V_at)mv medit.docbook $(srcdir)/medit.docbook
|
||||
#
|
||||
# medit.html: $(docbook_files)
|
||||
# $(AM_V_GEN)xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl/html/docbook.xsl $(srcdir)/medit.docbook > medit.html.tmp && \
|
||||
# mv medit.html.tmp $(srcdir)/medit.html
|
||||
|
||||
src_texinfo_files = \
|
||||
medit.texi \
|
||||
prefs.texi \
|
||||
prefs-file.texi \
|
||||
user-tools.texi \
|
||||
regex.texi \
|
||||
license.texi \
|
||||
script.texi
|
||||
|
||||
medit.texi: medit.texi.in $(top_builddir)/config.status
|
||||
$(AM_V_GEN)cd $(top_builddir) && ./config.status --silent --file=doc/medit.texi
|
||||
$(AM_V_at)mv medit.texi $(srcdir)/medit.texi
|
||||
$(srcdir)/medit-defines.ent: medit-defines.ent.in $(top_builddir)/config.status
|
||||
$(AM_V_GEN)cd $(top_builddir) && ./config.status --silent --file=doc/medit-defines.ent
|
||||
$(AM_V_at)mv medit-defines.ent $(srcdir)/medit-defines.ent
|
||||
|
||||
gendocbook_files = \
|
||||
$(top_srcdir)/api/gendocbook.py \
|
||||
@ -33,60 +12,85 @@ gendocbook_files = \
|
||||
$(top_srcdir)/api/mpi/module.py \
|
||||
$(top_srcdir)/api/mpi/docbookwriter.py
|
||||
|
||||
script-python.docbook: $(gendocbook_files) $(top_srcdir)/api/moo.xml
|
||||
$(srcdir)/script-python.docbook: $(gendocbook_files) $(top_srcdir)/api/moo.xml
|
||||
$(AM_V_GEN)$(PYTHON) $(top_srcdir)/api/gendocbook.py --python $(top_srcdir)/api/moo.xml \
|
||||
> script-python.docbook.tmp && mv script-python.docbook.tmp $(srcdir)/script-python.docbook
|
||||
|
||||
script-lua.docbook: $(gendocbook_files) $(top_srcdir)/api/moo.xml
|
||||
$(srcdir)/script-lua.docbook: $(gendocbook_files) $(top_srcdir)/api/moo.xml
|
||||
$(AM_V_GEN)$(PYTHON) $(top_srcdir)/api/gendocbook.py --lua $(top_srcdir)/api/moo.xml \
|
||||
> script-lua.docbook.tmp && mv script-lua.docbook.tmp $(srcdir)/script-lua.docbook
|
||||
|
||||
script-lua-gtk.docbook: $(gendocbook_files) $(top_srcdir)/moo/moolua/gtk.xml
|
||||
$(srcdir)/script-lua-gtk.docbook: $(gendocbook_files) $(top_srcdir)/moo/moolua/gtk.xml
|
||||
$(AM_V_GEN)$(PYTHON) $(top_srcdir)/api/gendocbook.py --lua $(top_srcdir)/moo/moolua/gtk.xml \
|
||||
> script-lua-gtk.docbook.tmp && mv script-lua-gtk.docbook.tmp $(srcdir)/script-lua-gtk.docbook
|
||||
|
||||
help/script-python.html: script-python.docbook script.xsl help/index.html
|
||||
$(srcdir)/help/script-python.html: script-python.docbook medit-defines.ent script.xsl
|
||||
$(AM_V_at)$(MKDIR_P) $(srcdir)/help/
|
||||
$(AM_V_GEN)xsltproc --output script-python.html.tmp \
|
||||
$(srcdir)/script.xsl $(srcdir)/script-python.docbook \
|
||||
&& mv script-python.html.tmp $(srcdir)/help/script-python.html
|
||||
|
||||
help/script-lua.html: script-lua.docbook script.xsl help/index.html
|
||||
$(srcdir)/help/script-lua.html: script-lua.docbook medit-defines.ent script.xsl
|
||||
$(AM_V_at)$(MKDIR_P) $(srcdir)/help/
|
||||
$(AM_V_GEN)xsltproc --output script-lua.html.tmp \
|
||||
$(srcdir)/script.xsl $(srcdir)/script-lua.docbook \
|
||||
&& mv script-lua.html.tmp $(srcdir)/help/script-lua.html
|
||||
|
||||
help/script-lua-gtk.html: script-lua-gtk.docbook script.xsl help/index.html
|
||||
$(srcdir)/help/script-lua-gtk.html: script-lua-gtk.docbook medit-defines.ent script.xsl
|
||||
$(AM_V_at)$(MKDIR_P) $(srcdir)/help/
|
||||
$(AM_V_GEN)xsltproc --output script-lua-gtk.html.tmp \
|
||||
$(srcdir)/script.xsl $(srcdir)/script-lua-gtk.docbook \
|
||||
&& mv script-lua-gtk.html.tmp $(srcdir)/help/script-lua-gtk.html
|
||||
|
||||
help/script.css: script.css
|
||||
$(AM_V_GEN)cp $(srcdir)/script.css $(srcdir)/help/
|
||||
$(srcdir)/help/medit.css: medit.css
|
||||
$(AM_V_at)$(MKDIR_P) $(srcdir)/help/
|
||||
$(AM_V_GEN)cp $(srcdir)/medit.css $(srcdir)/help/
|
||||
|
||||
help/index.html: $(src_texinfo_files)
|
||||
$(AM_V_at)rm -f $(srcdir)/help/*.html
|
||||
$(AM_V_at)$(MKDIR_P) $(srcdir)/help
|
||||
$(AM_V_GEN)cd $(srcdir) && makeinfo --html medit.texi
|
||||
$(srcdir)/lgpl.no-fancy-chars: $(top_srcdir)/COPYING
|
||||
tr -d '\014' < $(top_srcdir)/COPYING > lgpl.no-fancy-chars.tmp && \
|
||||
mv lgpl.no-fancy-chars.tmp $(srcdir)/lgpl.no-fancy-chars
|
||||
|
||||
help/help.html: help/index.html
|
||||
$(AM_V_GEN)cd $(srcdir) && makeinfo --html --no-split medit.texi && mv help.html help/
|
||||
docbook_files = \
|
||||
medit.docbook \
|
||||
prefs.docbook \
|
||||
regex.docbook \
|
||||
user-tools.docbook \
|
||||
license.docbook
|
||||
|
||||
help-sections.h.stamp: help/index.html $(srcdir)/gensections.py
|
||||
$(AM_V_GEN)$(PYTHON) $(srcdir)/gensections.py $(srcdir)/help/*.html > help-sections.h.tmp && \
|
||||
(cmp -s help-sections.h.tmp $(srcdir)/help-sections.h || mv help-sections.h.tmp $(srcdir)/help-sections.h)
|
||||
$(AM_V_at)rm -f help-sections.h.tmp
|
||||
$(AM_V_at)echo stamp > help-sections.h.stamp
|
||||
docbook_sources = \
|
||||
$(docbook_files) \
|
||||
lgpl.no-fancy-chars \
|
||||
medit-defines.ent
|
||||
|
||||
$(srcdir)/help/index.html: $(docbook_sources) medit.xsl medit-common.xsl
|
||||
$(AM_V_GEN)cd $(srcdir) && xsltproc --xinclude medit.xsl medit.docbook
|
||||
|
||||
$(srcdir)/help/help.html: $(docbook_sources) medit-single.xsl medit-common.xsl
|
||||
$(AM_V_at)$(MKDIR_P) $(srcdir)/help/
|
||||
$(AM_V_GEN)xsltproc --xinclude --output help.html.tmp $(srcdir)/medit-single.xsl $(srcdir)/medit.docbook && \
|
||||
mv help.html.tmp $(srcdir)/help/help.html
|
||||
|
||||
toc.xml: $(docbook_sources)
|
||||
$(AM_V_GEN)xsltproc --output toc.xml --xinclude \
|
||||
--stringparam chunk.first.sections 1 \
|
||||
http://docbook.sourceforge.net/release/xsl/current/html/maketoc.xsl $(srcdir)/medit.docbook
|
||||
|
||||
moo-help-sections.h.stamp: $(docbook_files) toc.xml genhelpsectionsh.py
|
||||
$(AM_V_GEN)$(PYTHON) $(srcdir)/genhelpsectionsh.py --toc=toc.xml --srcdir=$(srcdir) $(docbook_files) > moo-help-sections.h.tmp
|
||||
$(AM_V_at)cmp -s moo-help-sections.h.tmp $(srcdir)/moo-help-sections.h || mv moo-help-sections.h.tmp $(srcdir)/moo-help-sections.h
|
||||
$(AM_V_at)rm -f moo-help-sections.h.tmp
|
||||
$(AM_V_at)echo stamp > moo-help-sections.h.stamp
|
||||
|
||||
all-am: doc
|
||||
doc: \
|
||||
help/index.html \
|
||||
help/help.html \
|
||||
help/script-lua.html \
|
||||
help/script-lua-gtk.html \
|
||||
help/script-python.html \
|
||||
help/script.css \
|
||||
help-sections.h.stamp \
|
||||
medit.1
|
||||
doc: \
|
||||
$(srcdir)/help/index.html \
|
||||
$(srcdir)/help/help.html \
|
||||
$(srcdir)/help/script-lua.html \
|
||||
$(srcdir)/help/script-lua-gtk.html \
|
||||
$(srcdir)/help/script-python.html \
|
||||
$(srcdir)/help/medit.css \
|
||||
$(srcdir)/medit.1 \
|
||||
moo-help-sections.h.stamp
|
||||
|
||||
man-medit.t2t: man-medit.t2t.in $(top_builddir)/config.status
|
||||
$(AM_V_GEN)cd $(top_builddir) && ./config.status --silent --file=doc/man-medit.t2t
|
||||
@ -98,7 +102,7 @@ medit.1: man-medit.t2t
|
||||
|
||||
endif
|
||||
|
||||
EXTRA_DIST = help help-sections.h medit.1
|
||||
EXTRA_DIST = help moo-help-sections.h medit.1
|
||||
|
||||
install-data-local:
|
||||
$(MKDIR_P) $(DESTDIR)$(MOO_HELP_DIR)
|
||||
|
||||
69
doc/genhelpsectionsh.py
Normal file
69
doc/genhelpsectionsh.py
Normal file
@ -0,0 +1,69 @@
|
||||
#! /usr/bin/env python
|
||||
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
import optparse
|
||||
|
||||
op = optparse.OptionParser()
|
||||
op.add_option("--toc", action="store")
|
||||
op.add_option("--srcdir", action="store")
|
||||
(opts, args) = op.parse_args()
|
||||
|
||||
srcdir = opts.srcdir or '.'
|
||||
|
||||
def resolve_filename(filename):
|
||||
if os.path.exists(filename):
|
||||
return filename
|
||||
fullname = os.path.join(srcdir, filename)
|
||||
if os.path.exists(fullname):
|
||||
return fullname
|
||||
raise RuntimeError('could not find file %s' % filename)
|
||||
|
||||
def parse_toc(filename):
|
||||
filename = resolve_filename(filename)
|
||||
dic = {}
|
||||
for line in open(filename):
|
||||
m = re.search(r'<tocentry linkend="([\w\d_.-]+)"><\?dbhtml filename="([\w\d_.-]+)"\?>', line)
|
||||
if m:
|
||||
dic[m.group(1)] = m.group(2)
|
||||
return dic
|
||||
|
||||
def parse_docbook(filename):
|
||||
filename = resolve_filename(filename)
|
||||
dic = {}
|
||||
for line in open(filename):
|
||||
m = re.search(r'id\s*=\s*"([\w\d_.-]+)"\s+moo.helpsection\s*=\s*"([\w\d_.-]+)"', line)
|
||||
if m:
|
||||
dic[m.group(2)] = m.group(1)
|
||||
else:
|
||||
m = re.search(r'moo.helpsection\s*=\s*"([\w\d_.-]+)"\s+id\s*=\s*"([\w\d_.-]+)"', line)
|
||||
if m:
|
||||
dic[m.group(1)] = m.group(2)
|
||||
return dic
|
||||
|
||||
map_id_to_html = parse_toc(opts.toc)
|
||||
map_hsection_to_id = {}
|
||||
for f in args:
|
||||
map_hsection_to_id.update(parse_docbook(f))
|
||||
|
||||
map_hsection_to_html = {
|
||||
'PREFS_ACCELS': 'index.html',
|
||||
'PREFS_PLUGINS': 'index.html',
|
||||
'DIALOG_REPLACE': 'index.html',
|
||||
'DIALOG_FIND': 'index.html',
|
||||
'FILE_SELECTOR': 'index.html',
|
||||
'DIALOG_FIND_FILE': 'index.html',
|
||||
'DIALOG_FIND_IN_FILES': 'index.html',
|
||||
}
|
||||
|
||||
for section in map_hsection_to_id:
|
||||
map_hsection_to_html[section] = os.path.basename(map_id_to_html[map_hsection_to_id[section]])
|
||||
|
||||
print '#ifndef MOO_HELP_SECTIONS_H'
|
||||
print '#define MOO_HELP_SECTIONS_H'
|
||||
print ''
|
||||
for section in sorted(map_hsection_to_html.keys()):
|
||||
print '#define HELP_SECTION_%s "%s"' % (section, map_hsection_to_html[section])
|
||||
print ''
|
||||
print '#endif /* MOO_HELP_SECTIONS_H */'
|
||||
@ -1,32 +0,0 @@
|
||||
import os
|
||||
import sys
|
||||
import re
|
||||
|
||||
re_section = re.compile('<!-- moo-help-section: (\S+) -->')
|
||||
sections = [
|
||||
[ 'PREFS_ACCELS', 'index.html' ],
|
||||
[ 'PREFS_DIALOG', 'index.html' ],
|
||||
[ 'PREFS_PLUGINS', 'index.html' ],
|
||||
[ 'DIALOG_REPLACE', 'index.html' ],
|
||||
[ 'DIALOG_FIND', 'index.html' ],
|
||||
[ 'PREFS_FILE_SELECTOR', 'index.html' ],
|
||||
[ 'FILE_SELECTOR', 'index.html' ],
|
||||
[ 'DIALOG_FIND_FILE', 'index.html' ],
|
||||
[ 'DIALOG_FIND_IN_FILES', 'index.html' ],
|
||||
]
|
||||
|
||||
for f in sys.argv[1:]:
|
||||
if not os.path.basename(f) in ['help.html', 'script-lua.html', 'script-lua-gtk.html', 'script-python.html']:
|
||||
for line in open(f):
|
||||
m = re_section.search(line)
|
||||
if m:
|
||||
sections.append([m.group(1), f])
|
||||
break
|
||||
|
||||
print '#ifndef MOO_HELP_SECTIONS_H'
|
||||
print '#define MOO_HELP_SECTIONS_H'
|
||||
print ''
|
||||
for sec, filename in sorted(sections):
|
||||
print '#define HELP_SECTION_%s "%s"' % (sec, os.path.basename(filename))
|
||||
print ''
|
||||
print '#endif /* MOO_HELP_SECTIONS_H */'
|
||||
@ -1,31 +1,18 @@
|
||||
#ifndef MOO_HELP_SECTIONS_H
|
||||
#define MOO_HELP_SECTIONS_H
|
||||
|
||||
#define HELP_SECTION_APP_LICENSE "License.html"
|
||||
#define HELP_SECTION_APP_LICENSE "ch04.html"
|
||||
#define HELP_SECTION_DIALOG_FIND "index.html"
|
||||
#define HELP_SECTION_DIALOG_FIND_FILE "index.html"
|
||||
#define HELP_SECTION_DIALOG_FIND_IN_FILES "index.html"
|
||||
#define HELP_SECTION_DIALOG_REPLACE "index.html"
|
||||
#define HELP_SECTION_EDITING_OPTIONS "Options-for-editing-text.html"
|
||||
#define HELP_SECTION_FILE_SELECTOR "index.html"
|
||||
#define HELP_SECTION_LICENSE_GPL "GNU-GPL.html"
|
||||
#define HELP_SECTION_LICENSE_LFS "LuaFileSystem-License.html"
|
||||
#define HELP_SECTION_LICENSE_LGPL "GNU-LGPL.html"
|
||||
#define HELP_SECTION_LICENSE_LUA "Lua-License.html"
|
||||
#define HELP_SECTION_LICENSE_XDG_UTILS "xdg_002dutils-License.html"
|
||||
#define HELP_SECTION_PREFS_ACCELS "index.html"
|
||||
#define HELP_SECTION_PREFS_DIALOG "index.html"
|
||||
#define HELP_SECTION_PREFS_FILE "prefs_002exml.html"
|
||||
#define HELP_SECTION_PREFS_FILE_FILTERS "File-filters-tab.html"
|
||||
#define HELP_SECTION_PREFS_FILE_SELECTOR "index.html"
|
||||
#define HELP_SECTION_PREFS_LANGS_AND_FILTERS "Preferences.html"
|
||||
#define HELP_SECTION_PREFS_LANGS_OPTIONS "Language-options-tab.html"
|
||||
#define HELP_SECTION_PREFS_DIALOG "ch01s01.html"
|
||||
#define HELP_SECTION_PREFS_FILE_SELECTOR "ch01s04.html"
|
||||
#define HELP_SECTION_PREFS_FILTERS "ch01s03.html"
|
||||
#define HELP_SECTION_PREFS_LANGS "ch01s02.html"
|
||||
#define HELP_SECTION_PREFS_PLUGINS "index.html"
|
||||
#define HELP_SECTION_REGEX "Regular-expressions.html"
|
||||
#define HELP_SECTION_SCRIPT "Scripting.html"
|
||||
#define HELP_SECTION_USER_TOOLS "User_002ddefined-tools.html"
|
||||
#define HELP_SECTION_USER_TOOLS_FILES "Storing-tools-in-files.html"
|
||||
#define HELP_SECTION_USER_TOOLS_MANAGING "Managing-tools.html"
|
||||
#define HELP_SECTION_USER_TOOLS_SHELL_SCRIPTS "Shell-scripts.html"
|
||||
#define HELP_SECTION_USER_TOOLS "ch03.html"
|
||||
|
||||
#endif /* MOO_HELP_SECTIONS_H */
|
||||
|
||||
@ -1,40 +1,47 @@
|
||||
@node License
|
||||
@unnumbered License
|
||||
@helpsection{APP_LICENSE}
|
||||
<?xml version="1.0"?>
|
||||
<!DOCTYPE chapter [
|
||||
<!ENTITY % medit-defines SYSTEM "medit-defines.ent">
|
||||
%medit-defines;
|
||||
]>
|
||||
<chapter id="chapter-license" moo.helpsection="APP_LICENSE">
|
||||
<title>License</title>
|
||||
|
||||
@medit{} as a whole is distributed under the terms of the GNU General
|
||||
<para>
|
||||
&medit; as a whole is distributed under the terms of the GNU General
|
||||
Public License, version 2, but most of its code is released under the
|
||||
GNU Lesser General Public License. Full text of these licenses, as well
|
||||
as licenses and acknowledgements for third-party software incorporated
|
||||
in @medit{}, can be found in this section.
|
||||
in &medit;, can be found in this section.
|
||||
</para>
|
||||
|
||||
@menu
|
||||
* GNU GPL:: GNU General Public License
|
||||
* GNU LGPL:: GNU Lesser General Public License
|
||||
* Lua License:: Lua License
|
||||
* LuaFileSystem License:: LuaFileSystem License
|
||||
* xdg-utils License:: xdg-utils License
|
||||
@end menu
|
||||
|
||||
@node GNU GPL
|
||||
@section GNU General Public License
|
||||
@helpsection{LICENSE_GPL}
|
||||
@verbatiminclude ../COPYING.GPL
|
||||
<sect1 id="section-license-gpl">
|
||||
<title>GNU General Public License</title>
|
||||
<literallayout>
|
||||
<xi:include href="../COPYING.GPL" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
||||
</literallayout>
|
||||
</sect1>
|
||||
|
||||
@node GNU LGPL
|
||||
@section GNU Lesser General Public License
|
||||
@helpsection{LICENSE_LGPL}
|
||||
@verbatiminclude ../COPYING
|
||||
|
||||
@node Lua License
|
||||
@section Lua License
|
||||
@helpsection{LICENSE_LUA}
|
||||
@verbatiminclude ../moo/moolua/lua/COPYRIGHT
|
||||
<sect1 id="section-license-lgpl">
|
||||
<title>GNU Lesser General Public License</title>
|
||||
<literallayout>
|
||||
<xi:include href="lgpl.no-fancy-chars" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
||||
</literallayout>
|
||||
</sect1>
|
||||
|
||||
@node LuaFileSystem License
|
||||
@section LuaFileSystem License
|
||||
@helpsection{LICENSE_LFS}
|
||||
@verbatim
|
||||
|
||||
<sect1 id="section-license-lua">
|
||||
<title>Lua License</title>
|
||||
<literallayout>
|
||||
<xi:include href="../moo/moolua/lua/COPYRIGHT" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
||||
</literallayout>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="section-license-lfs">
|
||||
<title>LuaFileSystem License</title>
|
||||
<literallayout>
|
||||
LuaFileSystem - File System Library for Lua
|
||||
Copyright 2003-2007 PUC-Rio
|
||||
http://www.keplerproject.org/luafilesystem
|
||||
@ -44,14 +51,15 @@ related to file systems offered by the standard Lua distribution. LuaFileSystem
|
||||
offers a portable way to access the underlying directory structure and file
|
||||
attributes. LuaFileSystem is free software and uses the same license as Lua 5.1
|
||||
Current version is 1.2.1.
|
||||
@end verbatim
|
||||
</literallayout>
|
||||
</sect1>
|
||||
|
||||
@node xdg-utils License
|
||||
@section xdg-utils License
|
||||
@helpsection{LICENSE_XDG_UTILS}
|
||||
@verbatim
|
||||
Copyright 2006, Kevin Krammer <kevin.krammer@gmx.at>
|
||||
Copyright 2006, Jeremy White <jwhite@codeweavers.com>
|
||||
|
||||
<sect1 id="section-license-xdg-utils">
|
||||
<title>xdg-utils License</title>
|
||||
<literallayout>
|
||||
Copyright 2006, Kevin Krammer <kevin.krammer@gmx.at>
|
||||
Copyright 2006, Jeremy White <jwhite@codeweavers.com>
|
||||
|
||||
LICENSE:
|
||||
|
||||
@ -72,4 +80,8 @@ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
||||
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
||||
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
||||
OTHER DEALINGS IN THE SOFTWARE.
|
||||
@end verbatim
|
||||
</literallayout>
|
||||
</sect1>
|
||||
|
||||
|
||||
</chapter>
|
||||
8
doc/medit-common.xsl
Normal file
8
doc/medit-common.xsl
Normal file
@ -0,0 +1,8 @@
|
||||
<?xml version='1.0'?>
|
||||
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
|
||||
|
||||
<xsl:param name="html.stylesheet" select="'medit.css'"/>
|
||||
<xsl:output method="html" indent="yes"/>
|
||||
<xsl:param name="chunker.output.indent" select="'yes'"/>
|
||||
|
||||
</xsl:stylesheet>
|
||||
6
doc/medit-defines.ent.in
Normal file
6
doc/medit-defines.ent.in
Normal file
@ -0,0 +1,6 @@
|
||||
<!-- -%- lang:none -%- -->
|
||||
<!ENTITY medit "<application>medit</application>">
|
||||
<!ENTITY medit-version "@MOO_DISPLAY_VERSION@">
|
||||
<!ENTITY medit-prefs-xml "<filename>$HOME/.local/share/medit-1/prefs.xml</filename>">
|
||||
<!ENTITY medit-user-tools-dir "<filename>$HOME/.local/share/medit-1/tools/</filename>">
|
||||
<!ENTITY medit-user-data-dir "<filename>$HOME/.local/share/medit-1/</filename>">
|
||||
9
doc/medit-single.xsl
Normal file
9
doc/medit-single.xsl
Normal file
@ -0,0 +1,9 @@
|
||||
<?xml version='1.0'?>
|
||||
<xsl:stylesheet
|
||||
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
|
||||
|
||||
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>
|
||||
|
||||
<xsl:import href="medit-common.xsl"/>
|
||||
|
||||
</xsl:stylesheet>
|
||||
19
doc/medit.docbook
Normal file
19
doc/medit.docbook
Normal file
@ -0,0 +1,19 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?><!-- -%- indent-width:1 -%- -->
|
||||
<!DOCTYPE book [
|
||||
<!ENTITY % medit-defines SYSTEM "medit-defines.ent">
|
||||
%medit-defines;
|
||||
]>
|
||||
<book id="medit-manual">
|
||||
|
||||
<bookinfo>
|
||||
<title>&medit; manual</title>
|
||||
<date>12/26/2010</date>
|
||||
<releaseinfo>&medit-version;</releaseinfo>
|
||||
</bookinfo>
|
||||
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="prefs.docbook"/>
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="regex.docbook"/>
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="user-tools.docbook"/>
|
||||
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="license.docbook"/>
|
||||
|
||||
</book>
|
||||
@ -1,47 +0,0 @@
|
||||
\input texinfo @c -*-texinfo-*-
|
||||
@setfilename help.info
|
||||
@settitle medit @MOO_DISPLAY_VERSION@ manual
|
||||
@c %**end of header
|
||||
|
||||
@macro medit
|
||||
medit
|
||||
@end macro
|
||||
|
||||
@macro uilabel{text}
|
||||
@emph{\text\}
|
||||
@end macro
|
||||
|
||||
@macro helpsection{id}
|
||||
@html
|
||||
<!-- moo-help-section: \id\ -->
|
||||
@end html
|
||||
@end macro
|
||||
|
||||
@titlepage
|
||||
@title Sample Title
|
||||
@end titlepage
|
||||
|
||||
@contents
|
||||
|
||||
@node Top
|
||||
@top medit
|
||||
|
||||
This manual is for medit version @MOO_DISPLAY_VERSION@.
|
||||
|
||||
@menu
|
||||
* Preferences:: Editor preferences.
|
||||
* meditrc:: Preferences files.
|
||||
* Regular expressions:: Regular expressions.
|
||||
* User-defined tools:: User-defined tools.
|
||||
* Scripting:: Scripting.
|
||||
* License:: License.
|
||||
@end menu
|
||||
|
||||
@include prefs.texi
|
||||
@include prefs-file.texi
|
||||
@include regex.texi
|
||||
@include user-tools.texi
|
||||
@include script.texi
|
||||
@include license.texi
|
||||
|
||||
@bye
|
||||
12
doc/medit.xsl
Normal file
12
doc/medit.xsl
Normal file
@ -0,0 +1,12 @@
|
||||
<?xml version='1.0'?>
|
||||
<xsl:stylesheet
|
||||
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
|
||||
|
||||
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>
|
||||
|
||||
<xsl:import href="medit-common.xsl"/>
|
||||
|
||||
<xsl:param name="base.dir" select="'help/'"/>
|
||||
<xsl:param name="chunk.first.sections" select="'1'"/>
|
||||
|
||||
</xsl:stylesheet>
|
||||
@ -1,32 +0,0 @@
|
||||
@node prefs.xml
|
||||
@chapter Preferences files
|
||||
@helpsection{PREFS_FILE}
|
||||
|
||||
@medit{} preferences are stored in @file{$HOME/.local/share/medit-1/prefs.xml} file.
|
||||
It is an XML file which may be edited to set preferences which have not found
|
||||
their place in the @uilabel{Preferences} dialog.
|
||||
|
||||
NOTE: @medit{} reads the preferences file on startup and writes it whenever @uilabel{OK}
|
||||
or @uilabel{Apply} button is clicked in the @uilabel{Preferences} dialog. Therefore, if you
|
||||
modify the preferences file, your changes may be overwritten, and they not take
|
||||
effect until you restart @medit{}.
|
||||
|
||||
The following "hidden" settings are available:
|
||||
@itemize @bullet
|
||||
@item
|
||||
@var{Editor/window_title}: Format of the window title. It is a string which may
|
||||
contain format sequences, which are percent sign followed by a character:
|
||||
@itemize @minus
|
||||
@item @code{%a}: application name;
|
||||
@item @code{%b}: current document basename;
|
||||
@item @code{%f}: full path of the current document;
|
||||
@item @code{%u}: URI of the current document;
|
||||
@item @code{%s}: the status of the current document, e.g. "@code{ [modified]}". It is prefixed
|
||||
with a space, so that "@code{%b%s}" produces a nice string;
|
||||
@item @code{%%}: the percent character.
|
||||
@end itemize
|
||||
Default value is "@code{%a - %f%s}" which produces something like "@code{@medit{} - /home/user/file [modified]}".
|
||||
@item
|
||||
@var{Editor/window_title_no_doc}: same as @code{Editor/window_title}, used when no document is open.
|
||||
Default value is "@code{%a}".
|
||||
@end itemize
|
||||
289
doc/prefs.docbook
Normal file
289
doc/prefs.docbook
Normal file
@ -0,0 +1,289 @@
|
||||
<?xml version="1.0"?>
|
||||
<!DOCTYPE chapter [
|
||||
<!ENTITY % medit-defines SYSTEM "medit-defines.ent">
|
||||
%medit-defines;
|
||||
]>
|
||||
<chapter id="chapter-prefs">
|
||||
<title>Preferences</title>
|
||||
|
||||
<sect1 id="section-prefs-dialog" moo.helpsection="PREFS_DIALOG">
|
||||
<title>Preferences dialog</title>
|
||||
<para>
|
||||
<guilabel>Languages and files</guilabel> tab in the <guilabel>Editor</guilabel>
|
||||
section of the <guilabel>Preferences</guilabel> dialog allows customizing
|
||||
how syntax highlighting language and editing options are chosen
|
||||
depending on the document filename, as well as setting editing options for
|
||||
all documents which use given language and choosing file patterns and mime types
|
||||
for which the given language should be used.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="section-language-options" moo.helpsection="PREFS_LANGS">
|
||||
<title>Language options tab</title>
|
||||
<para>
|
||||
Here you can set editing options on per-language basis, as well as define
|
||||
for which file patterns and mime types given language should be used.
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><guilabel>Language</guilabel> combo box</term>
|
||||
<listitem><para>
|
||||
Choose the language you want to customize. Settings for <code>None</code> will apply to
|
||||
documents for which no syntax highlighting language was chosen.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><guilabel>Mime types</guilabel></term>
|
||||
<listitem><para>
|
||||
Selected language will be used for files with these mime types, unless the language
|
||||
is chosen based on the filename or overridden in the <guilabel>File filters tab</guilabel> section.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><guilabel>Extensions</guilabel></term>
|
||||
<listitem><para>
|
||||
Selected language will be used for files whose filenames match these patterns,
|
||||
unless overridden in the <guilabel>File filters tab</guilabel> section.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><guilabel>Options</guilabel></term>
|
||||
<listitem><para>
|
||||
Default editing options to use in documents which use the given language. These
|
||||
options can be overridden using <guilabel>File filters tab</guilabel> section, and options set
|
||||
in the file text have a higher priority as well. See <xref linkend="section-editing-options"/>
|
||||
for format of this entry content.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="section-file-filters" moo.helpsection="PREFS_FILTERS">
|
||||
<title>File filters tab</title>
|
||||
<para>
|
||||
<guilabel>File filters tab</guilabel> section allows to customize editing options,
|
||||
as well as syntax highlighting language, on per-document basis using regular
|
||||
expressions which are matched against the document filename (globs can also be
|
||||
used, see below). Full file paths are used, so one can have per-directory settings.
|
||||
</para>
|
||||
<para>
|
||||
Use dollar if you need to match ends of filenames, e.g. "<code>\.doc$</code>" will work as
|
||||
"<code>*.doc</code>" pattern.
|
||||
</para>
|
||||
<para>
|
||||
The filters are applied in the order they appear in the list, one by one. All filters
|
||||
are applied to every file, so several filters may affect options in the same file. In
|
||||
this way one can set some options for a set of files or a directory, then set or modify
|
||||
some additional options for certain files in that set, etc.
|
||||
</para>
|
||||
<para>
|
||||
To add a filter, use <guilabel>New</guilabel> button. Click the filter in the list to
|
||||
select it, then click the <guilabel>Filter</guilabel> or <guilabel>Options</guilabel>
|
||||
part of it to edit. Use <guilabel>Delete</guilabel> button to delete a filter,
|
||||
and <guilabel>Up</guilabel> and <guilabel>Down</guilabel> buttons to change the order in
|
||||
which they are applied.
|
||||
</para>
|
||||
<para>
|
||||
<guilabel>Filter</guilabel> field contains a regular expression matched agains the
|
||||
document filename. If it is found in the filename, then the options from the
|
||||
<guilabel>Options</guilabel> field are applied to the document. Alternatively it can be
|
||||
a comma-separated list of globs prefixed with "<code>globs:</code>" or a list
|
||||
of language ids prefixed with "<code>langs:</code>", e.g. "<code>globs:*.c,*.h</code>" or
|
||||
"<code>langs:c,c++</code>".
|
||||
</para>
|
||||
<para>
|
||||
<guilabel>Options</guilabel> field contains the options, in format described in
|
||||
<xref linkend="section-editing-options"/>.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="section-prefs-file-selector" moo.helpsection="PREFS_FILE_SELECTOR">
|
||||
<title><guilabel>File Selector</guilabel> tab</title>
|
||||
<para>
|
||||
<guilabel>File Selector</guilabel> tab in the <guilabel>Preferences</guilabel>
|
||||
dialog allows to define custom commands which are available in
|
||||
<guimenu>Open With</guimenu> submenu of context menu in File Selector. By default
|
||||
this submenu contains single item <guimenuitem>Default Application</guimenuitem>
|
||||
which opens selected file with default application as configured in the system.
|
||||
Here you can add additional commands and set whether they should be available
|
||||
only for given file patterns or syntax highlighting languages.
|
||||
</para>
|
||||
<para>
|
||||
Use <guilabel>New</guilabel> button to create new command, <guilabel>Delete</guilabel>
|
||||
button to delete selected command, and <guilabel>Up</guilabel> and <guilabel>Down</guilabel>
|
||||
to change relative order of the commands, they will appear in the menu in the same order
|
||||
as in this list.
|
||||
</para>
|
||||
<para>
|
||||
The following entries set the command properties:
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><parameter>Name</parameter></term>
|
||||
<listitem>Menu item label for this command.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>Command</parameter></term>
|
||||
<listitem>Shell command to execute when the menu item is activated. <code>%f</code> will
|
||||
be replaced with full path of the selected file. Example: <code>firefox %f</code></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>Extensions</parameter></term>
|
||||
<listitem>Semicolon-separated list of file patterns to define for which files this command
|
||||
is available, e.g. <code>*.c;*.h</code>. Leave it empty if the command should
|
||||
be available for all files.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>Mime types</parameter></term>
|
||||
<listitem>Semicolon-separated list of mime types to define for which files this command
|
||||
is available, e.g. <code>application/docbook+xml;application/x-glade</code>. Leave it empty
|
||||
if the command should be available for all files.</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="section-editing-options">
|
||||
<title>Options for editing text</title>
|
||||
<para>
|
||||
&medit; has some editing options which can be set in the document text,
|
||||
or in the <guilabel>Preferences</guilabel> dialog for sets of files or for given syntax
|
||||
highlighting language.
|
||||
</para>
|
||||
<para>
|
||||
To set the options in the document text, place the following on the first,
|
||||
second or the last line of the document:
|
||||
<programlisting>
|
||||
-%- <parameter>options</parameter> -%-
|
||||
</programlisting>
|
||||
where <parameter>options</parameter> is the option string
|
||||
<programlisting>
|
||||
<parameter>key</parameter>: <parameter>value</parameter>; <parameter>key</parameter>: <parameter>value</parameter>; ...
|
||||
</programlisting>
|
||||
(the latter is the format used also in the <guilabel>Preferences</guilabel> dialog).
|
||||
</para>
|
||||
<para>
|
||||
For example, the following might be the first line in a C file:
|
||||
<programlisting>
|
||||
/* -%- indent-width: 2; use-tabs: yes; strip: yes -%- */
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Values can be strings, integers, or booleans.
|
||||
</para>
|
||||
<para>
|
||||
Booleans are <code>yes</code>, <code>no</code>, <code>true</code>, <code>false</code>, <code>1</code>, <code>0</code>.
|
||||
</para>
|
||||
<para>
|
||||
If a string value contains <code>:</code> character, then the following syntax may be used:
|
||||
<code><parameter>key</parameter>=/<parameter>value</parameter>/</code>. Any character may be used instead of slash (and it
|
||||
must not occur in the <parameter>value</parameter>). Example: <code>word-chars=@-/:@</code>
|
||||
</para>
|
||||
<para>
|
||||
The following options are available:
|
||||
<variablelist>
|
||||
<?dbhtml list-presentation="table"?>
|
||||
<?dbhtml term-separator=" : "?>
|
||||
<varlistentry>
|
||||
<term><code>lang</code></term>
|
||||
<listitem><para>syntax highlighting language to use in this document. Special value <code>none</code> will
|
||||
turn off syntax highlighting in this document.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>strip</code></term>
|
||||
<listitem><para>a boolean value, whether trailing whitespace should be removed from the document on save.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>add-newline</code></term>
|
||||
<listitem><para>a boolean value, whether the editor should ensure that saved files have a trailing new line character.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>indent-width</code></term>
|
||||
<listitem><para>an integer specifying indentation offset used when the Tab key is pressed to indent text.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>tab-width</code></term>
|
||||
<listitem><para>displayed width of the Tab character. Note that this is <emphasis>not</emphasis> the same as
|
||||
<code>indent-width</code>.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>use-tabs</code></term>
|
||||
<listitem><para>whether the Tab character should be used for indentation.</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
<para>
|
||||
&medit; tries to understand modelines of Vim, Emacs, and Kate text editors, so chances are it will correctly
|
||||
pick up the conventional settings from source files.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="section-prefs-xml">
|
||||
<title>Preferences files</title>
|
||||
<para>
|
||||
&medit; preferences are stored in &medit-prefs-xml; file.
|
||||
It is an XML file which may be edited to set preferences which have not found
|
||||
their place in the <guilabel>Preferences</guilabel> dialog.
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
&medit; reads the preferences file on startup and writes it whenever <guilabel>OK</guilabel>
|
||||
or <guilabel>Apply</guilabel> button is clicked in the <guilabel>Preferences</guilabel> dialog. Therefore, if you
|
||||
modify the preferences file, your changes may be overwritten, and they not take
|
||||
effect until you restart &medit;.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
The following "hidden" settings are available:
|
||||
<variablelist>
|
||||
<?dbhtml term-separator=" : "?>
|
||||
<varlistentry>
|
||||
<term><parameter>Editor/window_title</parameter></term>
|
||||
<listitem><para>Format of the window title. It is a string which may
|
||||
contain format sequences, which are percent sign followed by a character:
|
||||
<variablelist>
|
||||
<?dbhtml list-presentation="table"?>
|
||||
<?dbhtml term-separator=" : "?>
|
||||
<varlistentry>
|
||||
<term><code>%a</code></term>
|
||||
<listitem>application name</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>%b</code></term>
|
||||
<listitem>current document basename</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>%f</code></term>
|
||||
<listitem>full path of the current document</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>%u</code></term>
|
||||
<listitem>URI of the current document</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>%s</code></term>
|
||||
<listitem>the status of the current document, e.g. "<code> [modified]</code>". It is prefixed
|
||||
with a space, so that "<code>%b%s</code>" produces a nice string</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>%%</code></term>
|
||||
<listitem>the percent character</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
Default value is "<code>%a - %f%s</code>" which produces something like "<code>medit - /home/user/file [modified]</code>".
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>Editor/window_title_no_doc</parameter></term>
|
||||
<listitem><para>same as <parameter>Editor/window_title</parameter>, used when no document is open.
|
||||
Default value is "<code>%a</code>".</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
</chapter>
|
||||
120
doc/prefs.texi
120
doc/prefs.texi
@ -1,120 +0,0 @@
|
||||
@node Preferences
|
||||
@chapter Selecting editing options and languages
|
||||
@helpsection{PREFS_LANGS_AND_FILTERS}
|
||||
|
||||
@uilabel{Languages and files} tab in the @uilabel{Editor}
|
||||
section of the @uilabel{Preferences} dialog allows customizing
|
||||
how syntax highlighting language and editing options are chosen
|
||||
depending on the document filename, as well as setting editing options for
|
||||
all documents which use given language and choosing file patterns and mime types
|
||||
for which the given language should be used.
|
||||
|
||||
@menu
|
||||
* Language options tab:: Language-specific options.
|
||||
* File filters tab:: Options based on file path.
|
||||
* Options for editing text:: Options for editing text.
|
||||
@end menu
|
||||
|
||||
@node Language options tab
|
||||
@section Language options tab
|
||||
@helpsection{PREFS_LANGS_OPTIONS}
|
||||
|
||||
Here you can set editing options on per-language basis, as well as define
|
||||
for which file patterns and mime types given language should be used.
|
||||
@table @asis
|
||||
@item @uilabel{Language} combo box
|
||||
Choose the language you want to customize. Settings for @code{None} will apply to
|
||||
documents for which no syntax highlighting language was chosen.
|
||||
@item @uilabel{Mime types}
|
||||
The given language will be used for files with these mime types, unless the language
|
||||
is chosen based on the filename or overridden in the @uilabel{File filters tab} section.
|
||||
@item @uilabel{Extensions}
|
||||
The given language will be used for files whose filenames match these patterns,
|
||||
unless overridden in the @uilabel{File filters tab} section.
|
||||
@item @uilabel{Options}
|
||||
Default editing options to use in documents which use the given language. These
|
||||
options can be overridden using @uilabel{File filters tab} section, and options set
|
||||
in the file text have a higher priority as well. See section @ref{Options for editing text}
|
||||
for the format of this entry content.
|
||||
@end table
|
||||
|
||||
|
||||
@node File filters tab
|
||||
@section File filters tab
|
||||
@helpsection{PREFS_FILE_FILTERS}
|
||||
|
||||
@uilabel{File filters tab} section allows to customize editing options,
|
||||
as well as syntax highlighting language, on per-document basis using regular
|
||||
expressions which are matched against the document filename (globs can also be
|
||||
used, see below). Full file paths are used, so one can have per-directory settings.
|
||||
|
||||
Use dollar if you need to match ends of filenames, e.g. "@code{\.doc$}" will work as
|
||||
"@code{*.doc}" pattern.
|
||||
|
||||
The filters are applied in the order they appear in the list, one by one. All filters
|
||||
are applied to every file, so several filters may affect options in the same file. In
|
||||
this way one can set some options for a set of files or a directory, then set or modify
|
||||
some additional options for certain files in that set, etc.
|
||||
|
||||
To add a filter, use @uilabel{New} button. Click the filter in the list to
|
||||
select it, then click the @uilabel{Filter} or @uilabel{Options}
|
||||
part of it to edit. Use @uilabel{Delete} button to delete a filter,
|
||||
and @uilabel{Up} and @uilabel{Down} buttons to change the order in
|
||||
which they are applied.
|
||||
|
||||
@uilabel{Filter} field contains a regular expression matched agains the
|
||||
document filename. If it is found in the filename, then the options from the
|
||||
@uilabel{Options} field are applied to the document. Alternatively it can be
|
||||
a comma-separated list of globs prefixed with "@code{globs:}" or a list
|
||||
of language ids prefixed with "@code{langs:}", e.g. "@code{globs:*.c,*.h}" or
|
||||
"@code{langs:c,c++}".
|
||||
|
||||
@uilabel{Options} field contains the options, in format described in
|
||||
section @ref{Options for editing text}.
|
||||
|
||||
|
||||
@node Options for editing text
|
||||
@section Options for editing text
|
||||
@helpsection{EDITING_OPTIONS}
|
||||
|
||||
@medit{} has some editing options which can be set in the document text,
|
||||
or in the @uilabel{Preferences} dialog for sets of files or for given syntax
|
||||
highlighting language.
|
||||
|
||||
To set the options in the document text, place the following on the first,
|
||||
second or the last line of the document:
|
||||
@example
|
||||
-%- @var{options} -%-
|
||||
@end example
|
||||
where @var{options} is the option string
|
||||
@example
|
||||
@var{key}: @var{value}; @var{key}: @var{value}; ...
|
||||
@end example
|
||||
(the latter is the format used also in the @uilabel{Preferences} dialog).
|
||||
|
||||
Values can be strings, integers, or booleans.
|
||||
|
||||
Booleans are @samp{yes}, @samp{no}, @samp{true}, @samp{false}, @samp{1}, @samp{0}.
|
||||
|
||||
If a string value contains @code{:} character, then the following syntax may be used:
|
||||
@code{@var{key}=/@var{value}/}. Any character may be used instead of slash (and it
|
||||
must not occur in the @var{value}). Example: @samp{word-chars=@@-/:@@}
|
||||
|
||||
The following options are available:
|
||||
@table @var
|
||||
@item lang
|
||||
syntax highlighting language to use in this document.
|
||||
@item strip
|
||||
a boolean value, whether trailing whitespace should be removed from the document on save.
|
||||
@item add-newline
|
||||
a boolean value, whether the editor should ensure that saved files have a trailing new line character.
|
||||
@item tab-width
|
||||
displayed width of the Tab character. NOTE: This is not an indentation offset, this is the visual width of a Tab character.
|
||||
@item use-tabs
|
||||
whether the Tab character should be used for indentation.
|
||||
@item indent-width
|
||||
an integer specifying indentation offset used when the Tab key is pressed to indent text.
|
||||
@end table
|
||||
|
||||
@medit{} tries to understand modelines of Vim, Emacs, and Kate text editors, so chances are it will correctly
|
||||
pick up the conventional settings from source files.
|
||||
23
doc/regex.docbook
Normal file
23
doc/regex.docbook
Normal file
@ -0,0 +1,23 @@
|
||||
<?xml version="1.0"?>
|
||||
<!DOCTYPE chapter [
|
||||
<!ENTITY % medit-defines SYSTEM "medit-defines.ent">
|
||||
%medit-defines;
|
||||
]>
|
||||
<chapter id="chapter-regex">
|
||||
<title>Regular expressions</title>
|
||||
|
||||
<para>
|
||||
&medit; uses regular expressions functionality provided by Glib, which in turn uses
|
||||
<ulink url="http://pcre.org/">PCRE</ulink> library. See
|
||||
<ulink url="http://library.gnome.org/devel/glib/stable/glib-regex-syntax.html">Glib manual</ulink>
|
||||
for complete description of regular expression syntax.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Regular expression searches in a document text are limited to single lines, unless the
|
||||
search pattern includes newline character. For example, pattern "<code>.*</code>" will match every
|
||||
line in the document, pattern "<code>.*\n.*</code>" will match pairs of consecutive lines. This means
|
||||
that it is mostly impossible to perform searches for text which spawns multiple lines.
|
||||
</para>
|
||||
|
||||
</chapter>
|
||||
@ -1,13 +0,0 @@
|
||||
@node Regular expressions
|
||||
@chapter Regular expressions
|
||||
@helpsection{REGEX}
|
||||
|
||||
@medit{} uses regular expressions functionality provided by Glib, which in turn uses
|
||||
@uref{http://pcre.org/, PCRE} library. See
|
||||
@uref{http://library.gnome.org/devel/glib/stable/glib-regex-syntax.html, Glib manual}
|
||||
for complete description of regular expression syntax.
|
||||
|
||||
Regular expression searches in a document text are limited to single lines, unless the
|
||||
search pattern includes newline character. For example, pattern "@code{.*}" will match every
|
||||
line in the document, pattern "@code{.*\n.*}" will match pairs of consecutive lines. This means
|
||||
that it is mostly impossible to perform searches for text which spawns multiple lines.
|
||||
@ -1,18 +0,0 @@
|
||||
@node Scripting
|
||||
@chapter Scripting
|
||||
@helpsection{SCRIPT}
|
||||
|
||||
@menu
|
||||
* Lua:: Lua
|
||||
* Python:: Python
|
||||
@end menu
|
||||
|
||||
@node Lua
|
||||
@section Lua
|
||||
@uref{script-lua.html, script-lua}
|
||||
|
||||
@uref{script-lua-gtk.html, script-lua-gtk}
|
||||
|
||||
@node Python
|
||||
@section Python
|
||||
@uref{script-python.html, script-python}
|
||||
@ -4,10 +4,8 @@
|
||||
|
||||
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>
|
||||
|
||||
<xsl:param name="html.stylesheet" select="'script.css'"/>
|
||||
|
||||
<xsl:output method="html"
|
||||
indent="yes"/>
|
||||
<xsl:param name="html.stylesheet" select="'medit.css'"/>
|
||||
<xsl:output method="html" indent="yes"/>
|
||||
|
||||
<!--<xsl:param name="variablelist.as.table" select="1"/>-->
|
||||
|
||||
|
||||
331
doc/user-tools.docbook
Normal file
331
doc/user-tools.docbook
Normal file
@ -0,0 +1,331 @@
|
||||
<?xml version="1.0"?><!-- -%- indent-width:1 -%- -->
|
||||
<!DOCTYPE chapter [
|
||||
<!ENTITY % medit-defines SYSTEM "medit-defines.ent">
|
||||
%medit-defines;
|
||||
]>
|
||||
<chapter id="chapter-user-tools" moo.helpsection="USER_TOOLS">
|
||||
<title>User-defined tools</title>
|
||||
|
||||
<para>
|
||||
&medit; allows extending its functionality with user-defined
|
||||
<parameter>tools</parameter>. It can be a Lua script or a Python script (if &medit; has been
|
||||
built with Python support) which are executed inside &medit;,
|
||||
or a shell script which can use the text of the open document as
|
||||
its input and/or output.
|
||||
</para>
|
||||
<para>
|
||||
There are some predefined tools which you can use as
|
||||
an example or to modify to suit your needs.
|
||||
</para>
|
||||
|
||||
|
||||
<sect1 id="section-managing-tools">
|
||||
<title>Managing tools</title>
|
||||
|
||||
<para>
|
||||
To create a new tool or to modify existing ones, open
|
||||
<guilabel>Preferences</guilabel> dialog and select <guilabel>Tools</guilabel> in the list on the left.
|
||||
</para>
|
||||
<para>
|
||||
Select the tool in the list or click the <guibutton>New</guibutton>
|
||||
button to create a new one. To modify the order in which the tools
|
||||
appear in the <guimenu>Tools</guimenu> menu (or in the document
|
||||
context menu), use <guibutton>Up</guibutton> and <guibutton>Down</guibutton> buttons. To rename a tool,
|
||||
click its name in the list to select it and then click again to
|
||||
edit the name. Use the <guibutton>Delete</guibutton> button to delete a tool.
|
||||
</para>
|
||||
<para>
|
||||
The following controls are available to modify the tools behavior:
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><guilabel>Files</guilabel></term>
|
||||
<listitem>Specifies for which files the tool is going to be available.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><guilabel>Options</guilabel></term>
|
||||
<listitem>Specifies under which conditions the tool should be enabled.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><guilabel>Command type</guilabel></term>
|
||||
<listitem>The type of the tool: a Python script, a Lua script, or a shell script.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><guilabel>Code</guilabel> text field</term>
|
||||
<listitem>Here you enter the actual script text.</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
<para>
|
||||
<guilabel>Options</guilabel> entry content is a comma-separated list of the following:
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><code>need-doc</code></term>
|
||||
<listitem>the tool needs an open document.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>need-file</code></term>
|
||||
<listitem>the tool will not work in new unsaved documents.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>need-save</code></term>
|
||||
<listitem>the document will be saved before the command is executed.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>need-save-all</code></term>
|
||||
<listitem>all open documents will be saved before the command is executed.</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
<para>
|
||||
<guilabel>Files</guilabel> entry content can be the following:
|
||||
<itemizedlist>
|
||||
<listitem>a comma-separated list of file patterns, e.g. <programlisting><code>*.c,*.h</code></programlisting></listitem>
|
||||
<listitem>a comma-separated list of languages prefixed with "<code>langs:</code>", e.g.
|
||||
<programlisting><code>langs: c, c++, objc</code></programlisting></listitem>
|
||||
<listitem>a regular expression matching document filename prefixed with "<code>regex:</code>", e.g. the above
|
||||
pattern list may be written as <programlisting><code>regex:\.[ch]$</code></programlisting></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
<para>
|
||||
Empty entry means that the tool will be available for all documents.
|
||||
</para>
|
||||
<para>
|
||||
Shell script tools also have the following controls available:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<guilabel>Input</guilabel> entry specifies what text from the document should be passed to the command via its standard input:
|
||||
<variablelist>
|
||||
<?dbhtml list-presentation="table"?>
|
||||
<varlistentry>
|
||||
<term><parameter>None</parameter></term>
|
||||
<listitem>no input text.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>Selected lines</parameter></term>
|
||||
<listitem>the lines containing selection or the line containing the cursor in
|
||||
case when no text is selected.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>Selection</parameter></term>
|
||||
<listitem>exact selected text. This will be different from <parameter>Selected lines</parameter>
|
||||
if selection does not span whole lines of the document, for instance if it is a single word.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>Whole document</parameter></term>
|
||||
<listitem>whole document contents.</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<guilabel>Output</guilabel> entry specifies how the standard output of the command should be redirected.
|
||||
<variablelist>
|
||||
<?dbhtml list-presentation="table"?>
|
||||
<varlistentry>
|
||||
<term><parameter>None</parameter></term>
|
||||
<listitem>the command output will be discarded.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>None, asynchronous</parameter></term>
|
||||
<listitem>the command output will be discarded, and the command will be executed in background.
|
||||
Use this if you need to launch some external program like a web browser.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>Output pane</parameter></term>
|
||||
<listitem>the command output will be displayed in an output pane. This is useful for running programs
|
||||
like compilers, where you want to see the output.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>Insert into the document</parameter></term>
|
||||
<listitem>output will be inserted into the current document at the cursor position. It will replace the
|
||||
text used as an input, if any.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>New document</parameter></term>
|
||||
<listitem>new document will be created and the command output will be inserted into it.</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<guilabel>Filter</guilabel> combo. If the output pane is used, then it can be passed through a
|
||||
<parameter>filter</parameter>: the filter can match filenames and line numbers, so when you click
|
||||
the text in the output pane it will open the corresponding file. This is used for compilers and
|
||||
similar commands, which output locations of errors in processed files.
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="section-storing-tools-in-files">
|
||||
<title>Storing tools in files</title>
|
||||
|
||||
<para>
|
||||
It is possible to create tools without using the <guilabel>Preferences</guilabel> dialog,
|
||||
they can be stored in files in <filename>tools</filename> subfolder of the &medit; data
|
||||
folders (or <filename>tools-context</filename> for tools which appear in the document context
|
||||
menu). In particular, on Unix systems you can place files into &medit-user-tools-dir; folder.
|
||||
</para>
|
||||
<para>
|
||||
Names of the files in the <filename>tools</filename> folder are used as their menu item
|
||||
labels, after stripping first three characters, so you can use trhee-character
|
||||
prefix to affect the order of the menu items, e.g. you can have <filename>00-Do Something</filename>,
|
||||
<filename>01-Another tool</filename> files to have them in that order in the menu. The files
|
||||
may be of three types:
|
||||
<itemizedlist>
|
||||
<listitem>files with extension "<filename>.py</filename>", they will be used
|
||||
as Python scripts;</listitem>
|
||||
<listitem>files with extension "<filename>.lua</filename>", they will be used
|
||||
as Lua scripts;</listitem>
|
||||
<listitem>executable files, they will be executed in the same way
|
||||
as shell commands.</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
<para>
|
||||
To set parameters for a tool, place them on the first or the second line of the file in
|
||||
the following format:
|
||||
<programlisting>
|
||||
!! <parameter>key</parameter>=<parameter>value</parameter>; <parameter>key</parameter>=<parameter>value</parameter>; ... !!
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
<parameter>key</parameter> may be one of the following:
|
||||
<variablelist>
|
||||
<?dbhtml list-presentation="table"?>
|
||||
<varlistentry>
|
||||
<term><code>position</code></term>
|
||||
<listitem>it can be <code>start</code> or <code>end</code>, and it defines whether the menu item
|
||||
will be located at the start or at the end of the menu.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>id</code></term>
|
||||
<listitem>the tool identificator.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>name</code></term>
|
||||
<listitem>the tool name, i.e. the label used in the menu item. Overrides the file name.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>accel</code></term>
|
||||
<listitem>default keyboard accelerator used to invoke this tool.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>menu</code></term>
|
||||
<listitem>the menu to place this tool into. By default the tools are located in the <guimenu>Tools</guimenu> menu,
|
||||
but they can be as well put into any other menu.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>langs</code></term>
|
||||
<listitem>comma-separated list of languages for which this tool will be enabled.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>file-filter</code></term>
|
||||
<listitem>defines for which files this tool will be enabled. The value has the same format as
|
||||
in the <guilabel>Preferences</guilabel> dialog.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>options</code></term>
|
||||
<listitem>same as the <guilabel>Options</guilabel> entry content in the <guilabel>Preferences</guilabel> dialog.</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
<para>
|
||||
In addition to these, you can set input and output options for executable files:
|
||||
<variablelist>
|
||||
<?dbhtml list-presentation="table"?>
|
||||
<varlistentry>
|
||||
<term><code>input</code></term>
|
||||
<listitem><code>none</code>, <code>lines</code>, <code>selection</code>, or <code>doc</code>.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>output</code></term>
|
||||
<listitem><code>none</code>, <code>async</code>, <code>pane</code>, <code>insert</code>, or <code>new-doc</code>.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><code>filter</code></term>
|
||||
<listitem>output filter name.</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="section-user-tools-shell">
|
||||
<title>Shell scripts</title>
|
||||
|
||||
<para>
|
||||
In addition to the document text passed via standard input,
|
||||
shell scripts have a number of environment variables set. <envar>APP_PID</envar>
|
||||
variable is set to the current process process id, so that opening a file in the
|
||||
same instance of &medit; is as simple as <code>medit filename</code> (on the other
|
||||
hand, you will have to use command line options if you need to run a new &medit; instance).
|
||||
The following environment variables are set when scripts are executed:
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><envar>DOC</envar></term>
|
||||
<listitem>document basename.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><envar>DOC_DIR</envar></term>
|
||||
<listitem>document directory. Full file path is
|
||||
<filename><envar>$DOC_DIR</envar>/<envar>$DOC</envar></filename>.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><envar>DOC_BASE</envar></term>
|
||||
<listitem>basename without extension.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><envar>DOC_EXT</envar></term>
|
||||
<listitem>document filename extension including the period. Basename is always
|
||||
<filename><envar>$DOC_BASE</envar><envar>$DOC_EXT</envar></filename>.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><envar>LINE</envar></term>
|
||||
<listitem>the number of the line containing cursor.</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><envar>DATA_DIR</envar></term>
|
||||
<listitem>user data directory (&medit-user-data-dir;). For example the tools are stored in
|
||||
<filename><envar>$DATA_DIR</envar>/menu.cfg</filename> file and in files in the
|
||||
<filename><envar>$DATA_DIR</envar>/tools/</filename> directory.</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
<para>
|
||||
Additionally, all shell commands which run inside &medit; will have
|
||||
<filename><envar>DATA_DIR</envar>/scripts</filename>
|
||||
directories in <envar>$PATH</envar>, so you may place some &medit;-specific programs
|
||||
or scripts into <filename><envar>DATA_DIR</envar>/scripts/</filename> to be used from shell script tools.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="section-user-tools-lua">
|
||||
<title>Lua scripts</title>
|
||||
|
||||
<para>
|
||||
<ulink url="script-lua.html">Medit API for Lua scripts</ulink>.
|
||||
</para>
|
||||
<para>
|
||||
<ulink url="script-lua-gtk.html">Gtk API for Lua scripts</ulink>.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="section-user-tools-python">
|
||||
<title>Python scripts</title>
|
||||
|
||||
<para>
|
||||
<ulink url="script-python.html">Medit API for Python scripts</ulink>.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
</chapter>
|
||||
@ -1,242 +0,0 @@
|
||||
@node User-defined tools
|
||||
@chapter User-defined tools
|
||||
@helpsection{USER_TOOLS}
|
||||
|
||||
@medit{} allows extending its functionality with user-defined
|
||||
@dfn{tools}. It can be a Lua or Python (provided @medit{} has been
|
||||
built with Python support) script which is executed inside @medit{},
|
||||
or a shell script which can use the text of the open document as
|
||||
its input and/or output.
|
||||
|
||||
There are some predefined tools which you can use as
|
||||
an example or to modify to suit your needs.
|
||||
|
||||
@menu
|
||||
* Managing tools:: Managing tools.
|
||||
* Storing tools in files:: Storing tools in files.
|
||||
@c * Lua scripts:: Lua scripts.
|
||||
* Shell scripts:: Shell scripts.
|
||||
@end menu
|
||||
|
||||
@node Managing tools
|
||||
@section Managing tools
|
||||
@helpsection{USER_TOOLS_MANAGING}
|
||||
|
||||
To create a new tool or to modify existing ones, open
|
||||
@uilabel{Preferences} dialog and select @uilabel{Tools} in the list on the left.
|
||||
|
||||
Select the tool in the list or click the @uilabel{New}
|
||||
button to create a new one. To modify the order in which the tools
|
||||
appear in the @uilabel{Tools} menu (or in the document
|
||||
context menu), use @uilabel{Up} and @uilabel{Down} buttons. To rename a tool,
|
||||
click its name in the list to select it and then click again to
|
||||
edit the name. Use the @uilabel{Delete} button to delete a tool.
|
||||
|
||||
The following controls are available to modify the tools behavior:
|
||||
@table @asis
|
||||
@item @uilabel{Files}
|
||||
Specifies for which files the tool is going to be available.
|
||||
@item @uilabel{Options}
|
||||
Specifies under which conditions the tool should be enabled.
|
||||
@item @uilabel{Command type}
|
||||
The type of the tool: a Python script, a Lua script, or a shell script.
|
||||
@item @uilabel{Code} text field
|
||||
Here you enter the actual script text.
|
||||
@end table
|
||||
|
||||
@uilabel{Options} entry content is a comma-separated list of the following:
|
||||
@table @var
|
||||
@item need-doc
|
||||
the tool needs an open document.
|
||||
@item need-file
|
||||
the tool will not work in new unsaved documents.
|
||||
@item need-save
|
||||
the document will be saved before the command is executed.
|
||||
@item need-save-all
|
||||
all open documents will be saved before the command is executed.
|
||||
@end table
|
||||
|
||||
@uilabel{Files} entry content can be the following:
|
||||
@itemize @bullet
|
||||
@item
|
||||
a comma-separated list of file patterns, e.g. "@code{*.c,*.h}";
|
||||
@item
|
||||
a comma-separated list of languages prefixed with "@code{langs:}", e.g. "@code{langs: c, c++, objc}";
|
||||
@item
|
||||
a regular expression matching document filename prefixed with "@code{regex:}", e.g. the above
|
||||
pattern list may be written as "@code{regex:\.[ch]$}".
|
||||
@end itemize
|
||||
|
||||
Empty entry means that the tool will be available for all documents.
|
||||
|
||||
Shell script tools also have the following controls available:
|
||||
|
||||
@uilabel{Input} entry specifies what text from the document should be passed to the command via its standard input:
|
||||
@table @uilabel
|
||||
@item None
|
||||
no input text.
|
||||
@item Selected lines
|
||||
the lines containing selection or the line containing the cursor in case when no text is selected.
|
||||
@item Selection
|
||||
exact selected text. This will be different from "Selected lines" if selection does not span whole lines of the document, for instance if it is a single word.
|
||||
@item Whole document
|
||||
whole document contents.
|
||||
@end table
|
||||
|
||||
@uilabel{Output} entry specifies how the standard output of the command should be redirected.
|
||||
@table @uilabel
|
||||
@item None
|
||||
the command output will be discarded.
|
||||
@item None, asynchronous
|
||||
the command output will be discarded, and the command will be executed in background.
|
||||
For instance, you should use this if you need to launch some external program like a web browser.
|
||||
@item Output pane
|
||||
the command output will be displayed in an output pane. This is useful for running programs
|
||||
like compilers, where you want to see the output.
|
||||
@item Insert into the document
|
||||
output will be inserted into the current document at the cursor position. It will replace the
|
||||
text used as an input, if any.
|
||||
@item New document
|
||||
new document will be created and the command output will be inserted into it.
|
||||
@end table
|
||||
|
||||
@uilabel{Filter} combo. If the output pane is used, then it can be passed through a @dfn{filter}:
|
||||
the filter can match filenames and line numbers, so when you click the text in the
|
||||
output pane it will open the corresponding file. This is used for compilers and similar
|
||||
commands, which output locations of errors in processed files.
|
||||
|
||||
|
||||
@node Storing tools in files
|
||||
@section Storing tools in files
|
||||
@helpsection{USER_TOOLS_FILES}
|
||||
|
||||
It is possible to create tools without using the @uilabel{Preferences} dialog,
|
||||
they can be stored in files in @file{tools} subfolder of the @medit{} data
|
||||
folders (or @file{tools-context} for tools which appear in the document context
|
||||
menu). In particular, on Unix systems you can place files into
|
||||
@file{$HOME/.local/share/@medit{}/tools/} folder.
|
||||
|
||||
Names of the files in the @file{tools} folder are used as their menu item
|
||||
labels, after stripping first three characters, so you can use trhee-character
|
||||
prefix to affect the order of the menu items, e.g. you can have @file{00-Do Something},
|
||||
@file{01-Another tool} files to have them in that order in the menu. The files
|
||||
may be of three types: files with extension "@file{.py}", they will be used
|
||||
as Python scripts; files with extension "@file{.lua}", they will be used
|
||||
as Lua scripts; and executable files, they will be executed in the same way
|
||||
as shell commands.
|
||||
|
||||
To set parameters for a tool, place them on the first or the second line of the file in
|
||||
the following format:
|
||||
@example
|
||||
!! @var{key}=@var{value}; @var{key}=@var{value}; ... !!
|
||||
@end example
|
||||
|
||||
@var{key} may be one of the following:
|
||||
@table @var
|
||||
@item position
|
||||
it can be ``start`` or ``end``, and defines whether the menu item will be located at the start or at the end of the menu.
|
||||
@item id
|
||||
the tool identificator.
|
||||
@item name
|
||||
the tool name, i.e. the label used in the menu item. Overrides the file name.
|
||||
@item accel
|
||||
default keyboard accelerator used to invoke this tool.
|
||||
@item menu
|
||||
the menu to place this tool into. By default the tools are located in the Tools menu, but they can be as well put into any other menu.
|
||||
@item langs
|
||||
comma-separated list of languages for which this tool will be enabled.
|
||||
@item file-filter
|
||||
defines for which files this tool will be enabled. The value has the same format as in the @uilabel{Preferences} dialog.
|
||||
@item options
|
||||
same as the @uilabel{Options} entry content in the @uilabel{Preferences} dialog.
|
||||
@end table
|
||||
|
||||
In addition to these, you can set input and output options for executable files:
|
||||
@table @var
|
||||
@item input
|
||||
can be @code{none}, @code{lines}, @code{selection}, or @code{doc}.
|
||||
@item output
|
||||
can be @code{none}, @code{async}, @code{pane}, @code{insert}, or @code{new-doc}.
|
||||
@item filter
|
||||
the output filter name.
|
||||
@end table
|
||||
|
||||
|
||||
@c @node Lua scripts
|
||||
@c @section Lua scripts
|
||||
@c
|
||||
@c Lua scripts can use the standard Lua library, ``lfs`` library, and ``medit`` package
|
||||
@c which provides some text editor API. Lua scripts have the following variables and functions available.
|
||||
@c
|
||||
@c - ``doc``: a table with the following fields:
|
||||
@c | ``file`` | the document file path. |
|
||||
@c | ``name`` | the document file basename.
|
||||
@c | ``dir`` | the document file directory.
|
||||
@c | ``ext`` | the document filename extension including the period.
|
||||
@c | ``base`` | the document filename without the extension: the basename is always ``base..ext``.
|
||||
@c - ``Cut()``, ``Copy()``, ``Paste()``: clipboard operations.
|
||||
@c - ``Backspace()``, ``Delete()``: corresponding key actions.
|
||||
@c - ``Up()``, ``Down()``, ``Left()``, ``Right()``: move cursor as the arrow keys do.
|
||||
@c - ``Selection()``: returns selected text as a string. Returns ``nil`` when no text is selected.
|
||||
@c - ``Select(n)``: selects ``n`` characters to the right if ``n`` is positive, and ``-n`` characters to the left if it is negative.
|
||||
@c - ``Insert(...)``: inserts text at cursor. Namely, it converts each argument to a string and inserts the result into the document.
|
||||
@c - ``NewLine()``: inserts new line character.
|
||||
@c
|
||||
@c The following functions are provided for more advanced text manipulation. Position in the
|
||||
@c document is denoted by the character offset from the beginning of the document, starting
|
||||
@c from 1, so the first character is at position 1. Functions which take or return ranges use pairs of
|
||||
@c offsets, a pair ``start``, ``end`` denotes range of text from
|
||||
@c ``start`` to ``end``, **not** including the character at offset ``end``. For instance, the
|
||||
@c single-character range consisting of the first character in the document corresponds to the
|
||||
@c pair ``1, 2``. Non-positive offset denotes the end of the document.
|
||||
@c
|
||||
@c - ``InsertText(pos, ...)``: inserts text at the position ``pos``.
|
||||
@c - ``DeleteText(start, end)``: deletes text in the range ``[start..end)``.
|
||||
@c - ``GetInsert()``: returns position of the cursor in the document.
|
||||
@c - ``GetSelectionBounds()``: returns positions of the selection start and end. If no text is
|
||||
@c selected, returns pair ``pos, pos`` where ``pos`` is the cursor position.
|
||||
@c - ``GetLine([pos])``: returns line number of the character at the position ``pos``. If ``pos``
|
||||
@c is not specified, it defaults to the cursor position.
|
||||
@c - ``GetPosAtLine(n)``: returns position at the beginning of the ``n``-th line.
|
||||
@c - ``LineStart([pos])``: returns the position of the beginning of the line which contains character at ``pos``.
|
||||
@c If ``pos`` is not specified, it defaults to the cursor position.
|
||||
@c - ``LineEnd([pos])``: returns the position of the end of the line which contains character at ``pos``.
|
||||
@c If ``pos`` is not specified, it defaults to the cursor position.
|
||||
@c - ``ForwardLine([pos, [n]])``: returns the position of the beginning of the next line (or
|
||||
@c ``n``-th line if ``n`` is specified). ``pos`` defaults to the cursor position if not
|
||||
@c specified.
|
||||
@c - ``BackwardLine([pos, [n]])``: returns the position of the beginning of the previous line
|
||||
@c (or ``n``-th line backwards if ``n`` is specified). ``pos`` defaults to the cursor position
|
||||
@c if not specified.
|
||||
@c - ``GetText(start, end)``: returns the text in the ``[start..end)``. If ``start == end``, it
|
||||
@c returns an empty string, not ``nil``.
|
||||
|
||||
|
||||
@node Shell scripts
|
||||
@section Shell scripts
|
||||
@helpsection{USER_TOOLS_SHELL_SCRIPTS}
|
||||
|
||||
In addition to the document text passed via standard input,
|
||||
shell scripts have a number of environment variables set. @env{APP_PID}
|
||||
variable is set to the current process process id, so that opening a file in the
|
||||
same instance of @medit{} is as simple as @code{@medit{} filename} (on the other
|
||||
hand, you will have to use command line options if you need to run a new @medit{} instance).
|
||||
The following environment variables are set when scripts are executed:
|
||||
@table @env
|
||||
@item DOC
|
||||
the document basename.
|
||||
@item DOC_DIR
|
||||
the document file directory. The full file path is @file{$DOC_DIR/$DOC}.
|
||||
@item DOC_BASE
|
||||
the basename without extension.
|
||||
@item DOC_EXT
|
||||
the document filename extension including the period. The basename is always @file{$DOC_BASE$DOC_EXT}.
|
||||
@item LINE
|
||||
the number of the line containing cursor.
|
||||
@item DATA_DIR
|
||||
the user data directory. For example the tools are stored in @file{$DATA_DIR/menu.cfg} file and in files in the @file{$DATA_DIR/tools/} directory.
|
||||
@end table
|
||||
|
||||
Additionally, all shell commands which run inside @medit{} will have @file{DATADIR/scripts}
|
||||
directories in @code{$PATH}, so you may place some @medit{}-specific programs
|
||||
or scripts into @file{USERDATADIR/scripts/} to be used from shell script tools.
|
||||
@ -25,7 +25,7 @@
|
||||
#include "mooutils/mooi18n.h"
|
||||
#include "mooutils/moodialogs.h"
|
||||
#include "mooutils/moohelp.h"
|
||||
#include "help-sections.h"
|
||||
#include "moo-help-sections.h"
|
||||
#include "mooapp/mooappabout-dialog-gxml.h"
|
||||
#include "mooapp/mooappabout-license-gxml.h"
|
||||
#include "mooapp/mooappabout-credits-gxml.h"
|
||||
|
||||
@ -33,7 +33,7 @@
|
||||
#include "mooedit/mooeditprefs-general-gxml.h"
|
||||
#include "mooedit/mooeditprefs-langs-gxml.h"
|
||||
#include "mooedit/mooeditprefs-view-gxml.h"
|
||||
#include "help-sections.h"
|
||||
#include "moo-help-sections.h"
|
||||
#include <string.h>
|
||||
|
||||
|
||||
@ -215,6 +215,7 @@ page_filters_init (MooPrefsPage *page)
|
||||
{
|
||||
PrefsFiltersXml *gxml = g_object_get_data (G_OBJECT (page), "moo-edit-prefs-page-xml");
|
||||
filter_treeview_init (gxml);
|
||||
moo_help_set_id (GTK_WIDGET (page), HELP_SECTION_PREFS_FILTERS);
|
||||
}
|
||||
|
||||
static void
|
||||
@ -347,7 +348,7 @@ page_langs_init (MooPrefsPage *page)
|
||||
PrefsLangsXml *gxml = g_object_get_data (G_OBJECT (page), "moo-edit-prefs-page-xml");
|
||||
MooTreeHelper *helper;
|
||||
|
||||
moo_help_set_id (GTK_WIDGET (page), HELP_SECTION_PREFS_LANGS_AND_FILTERS);
|
||||
moo_help_set_id (GTK_WIDGET (page), HELP_SECTION_PREFS_LANGS);
|
||||
|
||||
lang_combo_init (gxml->lang_combo, page, gxml);
|
||||
|
||||
|
||||
@ -46,7 +46,7 @@
|
||||
#include "mooutils/mooutils-debug.h"
|
||||
#include "mooutils/moohelp.h"
|
||||
#include "mooutils/mootype-macros.h"
|
||||
#include "help-sections.h"
|
||||
#include "moo-help-sections.h"
|
||||
#include <string.h>
|
||||
#include <gmodule.h>
|
||||
#include <gobject/gvaluecollector.h>
|
||||
|
||||
@ -27,7 +27,7 @@
|
||||
#include "mooutils/moocompat.h"
|
||||
#include "mooedit/mootextfind-gxml.h"
|
||||
#include "mooedit/mootextgotoline-gxml.h"
|
||||
#include "help-sections.h"
|
||||
#include "moo-help-sections.h"
|
||||
#include <gtk/gtk.h>
|
||||
#include <glib/gprintf.h>
|
||||
|
||||
|
||||
@ -27,7 +27,7 @@
|
||||
#include "mooutils/moohelp.h"
|
||||
#include "mooutils/moocompat.h"
|
||||
#include "mooutils/mooaccelprefs-gxml.h"
|
||||
#include "help-sections.h"
|
||||
#include "moo-help-sections.h"
|
||||
#include <gtk/gtk.h>
|
||||
#include <gdk/gdkkeysyms.h>
|
||||
#include <string.h>
|
||||
|
||||
@ -24,7 +24,7 @@
|
||||
#include "mooutils/moohelp.h"
|
||||
#include "mooutils/mooutils-treeview.h"
|
||||
#include "mooutils/moocompat.h"
|
||||
#include "help-sections.h"
|
||||
#include "moo-help-sections.h"
|
||||
|
||||
|
||||
enum {
|
||||
|
||||
@ -19,7 +19,7 @@
|
||||
#include "mooutils/mooi18n.h"
|
||||
#include "mooutils/moostock.h"
|
||||
#include "mooutils/moohelp.h"
|
||||
#include "help-sections.h"
|
||||
#include "moo-help-sections.h"
|
||||
#include "plugins/moofileselector-prefs-gxml.h"
|
||||
#include <gtk/gtk.h>
|
||||
#include <string.h>
|
||||
|
||||
@ -38,7 +38,7 @@
|
||||
#include "plugins/moofileselector-gxml.h"
|
||||
#include "mooutils/moohelp.h"
|
||||
#include "mooutils/mooatom.h"
|
||||
#include "help-sections.h"
|
||||
#include "moo-help-sections.h"
|
||||
#include <gmodule.h>
|
||||
#include <gtk/gtk.h>
|
||||
#include <gdk/gdkkeysyms.h>
|
||||
|
||||
@ -31,7 +31,7 @@
|
||||
#include "mooutils/mooutils-fs.h"
|
||||
#include "plugins/moofind-gxml.h"
|
||||
#include "plugins/moogrep-gxml.h"
|
||||
#include "help-sections.h"
|
||||
#include "moo-help-sections.h"
|
||||
#include <gtk/gtkdialog.h>
|
||||
#include <gtk/gtkscrolledwindow.h>
|
||||
#include <gtk/gtktogglebutton.h>
|
||||
|
||||
@ -22,7 +22,7 @@
|
||||
#include "mooutils/mooutils-treeview.h"
|
||||
#include "mooutils/moohelp.h"
|
||||
#include "plugins/usertools/moousertools-gxml.h"
|
||||
#include "help-sections.h"
|
||||
#include "moo-help-sections.h"
|
||||
#include <string.h>
|
||||
|
||||
enum {
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user