Skip to content

Commit

Permalink
Restructured asciidoc
Browse files Browse the repository at this point in the history
Broke the single large file into a single file per major section header. Renamed "Gremlin-Graph-Guide.adoc" to "Practical-Gremlin.adoc". Fixed up the doc build toolchain given latest installs of the tooling.
  • Loading branch information
spmallette committed Sep 28, 2023
1 parent adbfbc2 commit fcc0598
Show file tree
Hide file tree
Showing 15 changed files with 25,622 additions and 25,619 deletions.
12 changes: 7 additions & 5 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,10 @@
*.DS_Store
*.*~
*.*.*~
book/Gremlin-Graph-Guide.epub
book/Gremlin-Graph-Guide.html
book/Gremlin-Graph-Guide.mobi
book/Gremlin-Graph-Guide.pdf
book/Gremlin-Graph-Guide.xml
*.iml
**/.idea
book/Practical-Gremlin.epub
book/Practical-Gremlin.html
book/Practical-Gremlin.mobi
book/Practical-Gremlin.pdf
book/Practical-Gremlin.xml
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ This repository is the home for the source materials, sample code and examples f

**Quick Start - the latest version**

To read the latest snapshot of the book right away in a browser (HTML format) click [here](http://kelvinlawrence.net/book/PracticalGremlin.html) or for a PDF version click [here](http://kelvinlawrence.net/book/PracticalGremlin.pdf). These snapshots are updated regularly. You will find other formats including MOBI, EPUB and XML (Docbook) in the [releases](https://github.com/krlawrence/graph/releases) section. Formal releases will be published periodically assuming there is enough new material to make it worthwhile. If you want to see the absolute latest updates you can always browse the Asciidoc source file (Gremlin-Graph-Guide.adoc) in the /book folder. The PDF version is currently the "official" version. It has a better table of contents, some better formatting and a much nicer title page!
To read the latest snapshot of the book right away in a browser (HTML format) click [here](http://kelvinlawrence.net/book/PracticalGremlin.html) or for a PDF version click [here](http://kelvinlawrence.net/book/PracticalGremlin.pdf). These snapshots are updated regularly. You will find other formats including MOBI, EPUB and XML (Docbook) in the [releases](https://github.com/krlawrence/graph/releases) section. Formal releases will be published periodically assuming there is enough new material to make it worthwhile. If you want to see the absolute latest updates you can always browse the Asciidoc source files (Practical-Gremlin.adoc and Section-*.adoc files) in the /book folder. The PDF version is currently the "official" version. It has a better table of contents, some better formatting and a much nicer title page!

**LATEST NEWS:**
- [Sep-23-2023] Work has started on a second edition of the book! See the note below for more details.
Expand Down Expand Up @@ -56,7 +56,7 @@ The book introduces the Apache TinkerPop 3 Gremlin graph query and traversal lan

## How this site is organized

The book is being written using a text editor in AsciiDoc format. The source manuscript "Gremlin-Graph-Guide.adoc" can be found in the /book folder. This file will always reflect the most recent updates and will often be ahead of the other formats that will only be updated as part of a formal release. You will find formatted HTML and PDF versions of the book in the releases area. I have also provided DOCBOOK, EPUB and MOBI versions as part of each release. These can be viewed using many tools and e-book readers. Note that currently, only the HTML and PDF versions have all the nice colors for source code listings etc.
The book is being written using a text editor in AsciiDoc format. The source manuscript "Practical-Gremlin.adoc" can be found in the /book folder. This file will always reflect the most recent updates and will often be ahead of the other formats that will only be updated as part of a formal release. You will find formatted HTML and PDF versions of the book in the releases area. I have also provided DOCBOOK, EPUB and MOBI versions as part of each release. These can be viewed using many tools and e-book readers. Note that currently, only the HTML and PDF versions have all the nice colors for source code listings etc.

Included with the book are sample graph data (GraphML) and program files. You will find these, as well as some screen shots and images, and demos in the following folders.

Expand Down
25,604 changes: 0 additions & 25,604 deletions book/Gremlin-Graph-Guide.adoc

This file was deleted.

84 changes: 84 additions & 0 deletions book/Practical-Gremlin.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
PRACTICAL GREMLIN: An Apache TinkerPop Tutorial
===============================================
Kelvin R. Lawrence <gfxman@yahoo.com>
//v281 (TP 3.3.5), January 28th 2019
v283-preview, May 4th 2022
// vim: set tw=85 cc=+1 wrap spell redrawtime=20000:
// Wed May 04, 2022 08:20:08 CDT
//:Author: Kelvin R. Lawrence
//:Email: gfxman@yahoo.com
:Numbered:
:source-highlighter: pygments
:pygments-style: paraiso-dark
:title-logo-image: CoverArt.png
//:pygments-style: lovelace
//:source-highlighter: rouge
//:source-highlighter: coderay
//:pygments-style: native
//:pygments-style: monokai
//:pygments-style: manni
//:pygments-style: vim
:toc:
:toclevels: 4
:revision: 283-preview
//:revision: 281 (TP 3.3.5)
:doctype: book
:icons: font
//:pdf-page-size: Letter
:draftdate: May 4th 2022
:tpvercheck: 3.5.2

// NOTE1: I updated the paraiso-dark style so that source code with a style of text
// has a white foreground color. The default was unreadable,
// NOTE2: These notes are encoded using a minimal level of Asciidoc markup. You can read
// them as-is or generate HTML or other output formats from this file using the
// 'asciidoc' processor available on most Linux systems or via Cygwin on
// Windows. On Mac OS X the easiest way to install asciidoc is probably via
// Homebrew. You can also install Asciidoctor, a Ruby Gem, as an alternative to
// Asciidoc which is written in Python.
//
// NOTE3: In my tests, Asciidoctor seems a lot faster than Asciidoc and it has now become my
// preferred way of processing this file.
//
// As well as 'asciidoc' or Asciidoctor, the 'source-highlight' utility will also need to
// be installed if you want to process this file using Asciidoc and get source code
// highlighting. To get the table of contents to render correctly, the 'toclevels'
// setting needs to be set to 3 in asciidoc.conf. There are alternatives to
// 'source-highlight' such as Pygments that can also be used. Pygments, like
// source-highlight, will need to be installed before it can be used.
//
// Currently I find that Asciidoctor + pygments produces the most pleasing output.
//
// To use the Asciidoctor/Pygments combo you will need to install:
// 1. Asciidoctor (via gem)
// 2. pygments.rb (via gem)
//
// You probably should not need to manually install the pip piece as it is bundled
// in the Gem but if it does not work you may,
//
// 3. pygments (via pip)
//
// <img src="GremlinEaselNoText.png">
// <h1>PRACTICAL GREMLIN:<br>An Apache TinkerPop Tutorial</h1>
//<img src="PRACTICAL-GREMLIN-Revised-v2.png">
//<h1>PRACTICAL GREMLIN:<br>An Apache TinkerPop Tutorial</h1>

include::Section-Introduction.adoc[]

include::Section-Getting-Started.adoc[]

include::Section-Writing-Gremlin-Queries.adoc[]

include::Section-Beyond-Basic-Queries.adoc[]

include::Section-Miscellaneous-Queries-Results.adoc[]

include::Section-Moving-Beyond.adoc[]

include::Section-Introducing-Gremlin-Server.adoc[]

include::Section-Common-Serialization-Formats.adoc[]

include::Section-Further-Reading.adoc[]

// vim: set tw=85 cc=+1 wrap spell redrawtime=20000:
4 changes: 2 additions & 2 deletions book/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
![map](https://github.com/krlawrence/graph/raw/master/images/PRACTICAL-GREMLIN-Revised-v2.png?raw=true, "Book cover art")
This folder contains the AsciiDoc source file used to produce the HTML, XML (DOCBOOK), EPUB, MOBI and PDF output.
This folder contains the AsciiDoc source files used to produce the HTML, XML (DOCBOOK), EPUB, MOBI and PDF output.


**LATEST NEWS:**
Expand All @@ -26,7 +26,7 @@ NOTE: In order to prune the unwanted files from the project, as part of the v274

**About the files in this folder**

You can browse the 'Gremlin-Graph-Guide.adoc' file directly from within the GitHub (web interface) and it will work but you will not get the full color coding and other niceties that are present in the HTML and PDF versions as they have been run through an AsciiDoc processor and had various style sheets and code pretty printers applied. Your mileage may vary but I find the HTML version to be the most pleasing to read. The '.adoc' file will always contain the most recent updates. The other formats (HTML,DocBook,PDF,ePub and MOBI) will be generated once there are enough updates to make it worthwhile generating a 'release'. If you want to build the output format files yourself they can be generated by running the 'make-book.sh' script. The script assumes you have Asciidoctor installed (which is a Ruby Gem) as well as Pygments.rb (another Ruby Gem). To do the conversion to MOBI and EPUB the script assumes that Calibre and Pandoc are installed. I have successfuly built the book on several Linux distros including Ubuntu, CentOS and Red Hat. I have successfully used Asciidoctor on Mac OS as well but I always use Linux to produce the EPUB abd MOBI versions.
The 'Practical-Gremlin.adoc' file is the root file to the book that includes the other 'Section-*.adoc' files that make up its contents. You can browse the 'Practical-Gremlin.adoc' and the various 'Section-*.adoc' files directly from within the GitHub (web interface) and it will work, but you will not get the full color coding and other niceties that are present in the HTML and PDF versions as they have been run through an AsciiDoc processor and had various style sheets and code pretty printers applied. Your mileage may vary, but I find the HTML version to be the most pleasing to read. The '.adoc' files will always contain the most recent updates. The other formats (HTML,DocBook,PDF,ePub and MOBI) will be generated once there are enough updates to make it worthwhile generating a 'release'. If you want to build the output format files yourself they can be generated by running the 'make-book.sh' script. The script assumes you have Asciidoctor installed (which is a Ruby Gem) as well as Pygments.rb (another Ruby Gem). To do the conversion to MOBI and EPUB the script assumes that Calibre and Pandoc are installed. I have successfully built the book on several Linux distros including Ubuntu, CentOS and Red Hat. I have successfully used Asciidoctor on Mac OS as well, but I always use Linux to produce the EPUB abd MOBI versions.

To read the HTML file please either downloaded it to your computer or visit http://kelvinlawrence.net/book/PracticalGremlin.html as it is too big for Git to display inside its web user interface.

Expand Down
Loading

0 comments on commit fcc0598

Please sign in to comment.