Permalink
Browse files

Add HTML documentation from the website.

  • Loading branch information...
1 parent 5b935cd commit 458a6a737782306788ab092dadb5a6179695a82e @nickbnf committed Apr 13, 2010
Showing with 163 additions and 50 deletions.
  1. +1 −0 .gitignore
  2. +44 −0 README
  3. +0 −49 README.textile
  4. +66 −0 doc/documentation.markdown
  5. +31 −0 finish.sed
  6. +21 −1 glogg.pro
View
@@ -13,6 +13,7 @@ glogg
glogg_tests
massif.out*
core.*
+doc/*.html
# File generated by Qt Creator
glogg.config
View
44 README
@@ -0,0 +1,44 @@
+glogg - the fast, smart log explorer
+
+glogg is a multi-platform GUI application that helps browse and search
+through long and complex log files. It is designed with programmers and
+system administrators in mind and can be seen as a graphical, interactive
+combination of grep and less.
+
+## Main features
+
+* Runs on Unix-like systems, Windows and Mac thanks to Qt
+* Provides a second window showing the result of the current search
+* Supports grep/egrep like regular expressions
+* Colorizes the log and search results
+* Displays a context view of where in the log the lines of interest are
+* Is fast and reads the file directly from disk, without loading it into memory
+* Is open source, released under the GPL
+
+## Requirements
+
+* Qt libraries (version 4.3.0 or later)
+* Boost "program-options" library (optional, glogg can use a version included
+ in the tarball if the shared library is not installed)
+* Markdown HTML processor (optional, to generate HTML documentation)
+
+## Building
+
+The build system uses qmake. Building and installation is done this way:
+
+tar xzf glogg-X.X.X.tar.gz
+cd glogg-X.X.X
+qmake (or qmake-qt4)
+make
+make install INSTALL_ROOT=/usr/local (as root if needed)
+
+qmake USE_NATIVE_BOOST=1 will use the system wide Boost libraries (recommended
+if available).
+
+The documentation is built and installed if 'markdown' is found.
+
+## Contact
+
+Please visit glogg's website: http://glogg.bonnefon.org/
+
+The development mailing list is hosted at http://groups.google.co.uk/group/glogg-devel
View
@@ -1,49 +0,0 @@
-h1. glogg - A fast, advanced log explorer
-
-glogg is a multi-platform GUI application that helps browse and search
-through long and complex log files. It is designed with programmers and
-system administrators in mind and can be seen as a graphical, interactive
-combination of grep and less.
-
-h2. Main features
-* Runs on Unix-like systems, Windows and Mac thanks to Qt
-* Provides a second window showing the result of the current search
-* Supports grep/egrep like regular expressions
-* Colorizes the log and search results
-* Displays a context view of where in the log the lines of interest are
-* Is fast and reads the file directly from disk, without loading it into memory
-* Supports vim/less like keyboard commands to move around the file
-* Is open source, released under the GPL
-
-h2. Installation
-
-h3. Windows
-
-An up to date Windows installer is available at http://groups.google.com/group/glogg-devel/web
-
-h3. From source code
-
-For other platforms, you can build glogg from source.
-The source code is hosted on a git repository at git://github.com/nickbnf/glogg.git
-Building is to be done this way:
-
-<pre>
-<code>
-git clone git://github.com/nickbnf/glogg.git
-cd glogg
-qmake (or qmake-qt4 on debian/ubuntu)
-make
-make install INSTALL_ROOT=/usr/local (as root if needed)
-</code>
-</pre>
-
-You need to have the Qt development libraries installed (tested on version 4.3.0 and later).
-
-h2. Development
-
-glogg is mainly written and currently maintained by Nicolas Bonnefon
-(nicolas (at) bonnefon (dot) org). Feel free to send him any suggestion,
-patch, bug report...
-
-glogg has a github project page to allow people to keep in touch with the
-development at http://wiki.github.com/nickbnf/glogg
View
@@ -0,0 +1,66 @@
+
+## Getting started
+
+_glogg_ can be started from the command line, optionally passing the file to
+open as an argument, or via the desktop environment's menu or file
+association.
+If no file name is passed, _glogg_ will initially open the last used file.
+
+The main window is divided in three parts : the top displays the log file. The
+bottom part, called the "filtered view", shows the results of the search. The
+line separating the two contains the regular expression used as a filter.
+
+Entering a new regular expression, or a simple search term, will update the
+bottom view, displaying the results of the search. The lines matching the
+search criteria are listed in order in the results, and are marked with a red
+circle in both windows.
+
+## Exploring log files
+
+Regular expressions are a powerful way to extract the information you are
+interested in from the log file. _glogg_ uses _extended regular expressions_.
+
+One of the most useful regexp feature when exploring logs is the
+_alternation_, using parentheses and the | operator. It searches for several
+alternatives, permitting to display several line types in the filtered window,
+in the same order they appear in the log file.
+
+For example, to check that every connection opened is also closed, one can use
+an expression similar to:
+
+`Entering (Open|Close)Connection`
+
+Any 'open' call without a matching 'close' will immediately be obvious in the
+filtered window.
+The alternation also works with the whole search line. For example if you also
+want to know what kind of connection has been opened:
+
+`Entering (Open|Close)Connection|Created a .* connection`
+
+`.*` will match any sequence of character on a single line, but _glogg_ will only
+display lines with a space and the word `connection` somewhere after `Created a`
+
+## Using filters
+
+_Filters_ can colorize some lines of the log being displayed, for example to
+draw attention to lines indicating an error, or to associate a color with each
+sort of event. Any number of filter can be defined in the 'Filters'
+configuration dialog, each using a regexp against which lines will be matched.
+For each line, all filters are tried in order and the fore and back colors of
+the first successful filter are applied.
+
+## Browsing changing log files
+
+_glogg_ can display and search through logs while they are written to disk, as
+it might be the case when debugging a running program or server.
+The log is automatically updated when it grows, but the search must be
+manually restarted for the new matches to be found.
+
+## Settings
+### Font
+
+The font used to display the log file. A clear, monospace font (like the free,
+open source, [DejaVu Mono](http://www.dejavu-fonts.org/) for example) is
+recommended.
+
+
View
@@ -0,0 +1,31 @@
+# Add header/footer around the Markdown generated documentation
+# Copied from Damian Cugley (http://www.alleged.org.uk/2005/marky/)
+
+1 {
+ h
+ i\
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"\
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">\
+<html xml:lang="en-US" lang="en-US">\
+<head>
+ s/h2>/title>/g
+ rmetadata.inc
+ a\
+</head>\
+<body>
+ rheader.inc
+}
+
+2 {
+ x
+ p
+ x
+}
+
+$ {
+ rfooter.inc
+ a\
+</body>\
+</html>
+}
+
View
@@ -72,6 +72,25 @@ else {
RC_FILE = glogg.rc
RESOURCES = glogg.qrc
+# Build HTML documentation (if 'markdown' is available)
+system(type markdown >/dev/null) {
+ MARKDOWN += doc/documentation.markdown
+}
+else {
+ message("markdown not found, HTML doc will not be generated")
+}
+
+doc_processor.name = markdown
+doc_processor.input = MARKDOWN
+doc_processor.output = doc/${QMAKE_FILE_BASE}.html
+doc_processor.commands = markdown ${QMAKE_FILE_NAME} | \
+ sed -f finish.sed >${QMAKE_FILE_OUT}
+
+doc_processor.CONFIG += target_predeps
+doc_processor.variable_out = doc.files
+
+QMAKE_EXTRA_COMPILERS += doc_processor
+
# Install (for unix)
icon16.path = $$PREFIX/share/icons/hicolor/16x16/apps
icon16.files = images/hicolor/16x16/glogg.png
@@ -80,7 +99,7 @@ icon32.path = $$PREFIX/share/icons/hicolor/32x32/apps
icon32.files = images/hicolor/32x32/glogg.png
doc.path = $$PREFIX/share/doc/glogg
-doc.files = README.textile COPYING
+doc.files += README COPYING
desktop.path = $$PREFIX/share/applications
desktop.path = glogg.desktop
@@ -106,3 +125,4 @@ isEmpty(VERSION) {
else {
QMAKE_CXXFLAGS += -DGLOGG_VERSION=\\\"$$VERSION\\\"
}
+

0 comments on commit 458a6a7

Please sign in to comment.