#
#   Copyright (C) 2010-2021 Andreas Rönnquist
#   This file is distributed under the same license
#   as the sciteproj package, see COPYING file.
#


SciteProj
=========

SciteProj is a Project Manager for usage with the SciTE text editor.
It is based on ScitePM by Roy Wood. It is a "director" of SciTE, using
it's director interface to communicate between SciteProj and SciTE. See

http://www.scintilla.org/SciTEDirector.html

for more information. SciteProj is used to browse folders on the harddrive in
customizable ways. Previous versions used to load "projects" from XML files,
but this was dropped, and now sciteproj shows and works directly on your
harddrive contents filterable and sortable as you wish.


Running
=======

SciteProj will load a configuration from the file sciteprojrc.lua first in the
directory specified by $XDG_CONFIG_HOME each program start. This is most likely

~/.config/sciteprojrc.lua

or if that doesn't exist sciteproj will load config from sciteprojrc.lua in
the current folder.

See the following links on why we use the folder ~/.config/ :

http://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-get-user-config-dir
http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

Between 0.7 and 0.8 SciteProj has gone through some big changes, and changed
the way "projects" are handled. From now on sciteproj works directly on what
is available on the harddrive, and doesn't use a project XML file. However, if
you have a local sciteprojrc.lua in a folder, sciteproj will read information
from it and act on that to determine how to view the folder. Please notice that
I now use LUA, which amongst other means that boolean values are case sensitive
for lowercase and TRUE and FALSE are invalid as values.

The options available in the config file are:

* The window geometry

You can enter wanted window geometry/positioning, which will be applied to
the program upon next program start. The variables are xpos, ypos, width and
height.

Also, the following options exist:

* give_scite_focus
   If this is set to true, the SciTE window will recieve focus when you open
   a file from SciteProj. (Defaults to false)

* hide_statusbar
   Don't show the statusbar to save valuable screen-space.

* use_stock_folder_icon
   Should we use the system folder icon, or the ones provided by sciteproj?
   The sciteproj one are different icons for opened and closed directory,
   while when using the stock ones there are only one icon for folders, open or
   closed.

* start_scite
   Should SciTE be started simultaneously with sciteproj?

You can open this configuration file by opening the Edit menu and select Edit
Options in that menu. This will open sciteprojrc.lua from the current folder as
if it was part of your project and edit it in SciTE.

SciteProj will give you a warning if it isn't able to find the SciTE
executable on SciteProj start. As default SciTE will be searched for in
/usr/bin, /bin, and /usr/local/bin, under the names scite and SciTE. If it
isn't found there you will get a warning upon running. You can also use the
--scite flag when running to locate SciTE, for example

sciteproj --scite=/bin/scite

will look for the scite executable in the /bin/ folder. SciTE will also be
searched for in the path pointed to by the environment variable SciTE_HOME.

By pressing Ctrl+R or choosing "View Recently Opened Files" in the "View" menu,
you split up the project window in two parts, and the new part contain a list
of the most recently opened files in the project. The files in this list are
sorted so the ones you opened latest is at the top of the list (or bottom -
its configurable).

Local folder settings
=====================

SciteProj will load sciteprojrc.lua from the current folder. In this file you
can decide what files should be hidden and shown, what sort order should be used
per folder, and which folders should be open when starting sciteproj and not.
It follows LUA syntax, and uses three tables to filter hidden files, sort order,
and to determine which folders should be open on sciteproj start. (A table is
a lua type that implements associative arrays)

First, hide_filter should look something like this (lines starting with "--"
are comments, and not read by the LUA interpreter):

-- hide_filter
-- filters out files from the project listing - wildcards are allowed.
hide_filter = {
   -- ".gitignore",
   -- "src/*.h",
   -- "test",
   ".git",
   "obj",
   "old"
}

Second, sort-order is a table with folder-names as indexes:

-- sort_order
-- Here you can list folders and set their individual sort order.
--
-- 0 - ascending
-- 1 - descending
-- 2 - ascending by extension
-- 3 - descending by extension
--
-- default on folders that isn't listed here is 0 - ascending
--
sort_order = {
   ["./graphics/test/"] = 0,
   ["src"] = 2
}


a dot is the current folder, and all folder listed is below the "project" path
if a full path name isn't listed.

Last, open_folders is used to determine which folders should be open or closed
on sciteproj program start:

-- open folder - should a folder start as opened or closed?
-- all folders default to false
open_folders = {
   ["bin"] = true,
   ["src"] = true,
   ["src/test"] = false,
   ["po"] = false

}

If you want to use sciteproj and filter out files in project where you for
some reason don't want to (or can) add a sciteprojrc.lua, you can use a
global file in ~/.config/sciteprojrc.lua and add a variable like this:

hide_filter_global = {
                     "/home/gusnan/kod/git/sciteproj/sciteproj/obj"
                     }

This will hide the set folders in sciteproj.


Thats it! Enjoy using sciteproj!

Credits
=======

SciteProj is based on the program ScitePM written by Roy Wood and Martin
Andrews, and is developed by Andreas Rönnquist <andreas (at) ronnquist (dot) net>.

-----------------------------------
graphics/sciteproj.xpm

is based on the SciTE logo, which is licensed under the following license:

License for Scintilla and SciTE

Copyright 1998-2003 by Neil Hodgson <neilh@scintilla.org>

All Rights Reserved

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation.

NEIL HODGSON DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS, IN NO EVENT SHALL NEIL HODGSON BE LIABLE FOR ANY
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE
OR PERFORMANCE OF THIS SOFTWARE.

(see http://sourceforge.net/p/scintilla/scite/ci/default/tree/License.txt)

-----------------------------------
graphics/dir-open.xpm
graphics/dir-close.xpm

These icons are created by the Tango Desktop Project, and released under
Public Domain, see at the bottom of http://tango.freedesktop.org/ for
details.
