Docs: adding info about TPAC microdata + linked data
authorJane Sandberg <>
Sun, 17 Sep 2017 20:11:13 +0000 (13:11 -0700)
committerJane Sandberg <>
Sun, 17 Sep 2017 20:16:35 +0000 (13:16 -0700)
Signed-off-by: Jane Sandberg <>
docs/admin/sitemap_admin.adoc [new file with mode: 0644]
docs/admin_initial_setup/troubleshooting_tpac.adoc [new file with mode: 0644]
docs/opac/sitemap.adoc [new file with mode: 0644]
docs/opac/visibility_on_the_web.adoc [new file with mode: 0644]

diff --git a/docs/admin/sitemap_admin.adoc b/docs/admin/sitemap_admin.adoc
new file mode 100644 (file)
index 0000000..50bcd82
--- /dev/null
@@ -0,0 +1,42 @@
+Running the sitemap generator
+The `sitemap_generator` script must be invoked with the following argument:
+* `--lib-hostname`: specifies the hostname for the catalog (for example,
+  `--lib-hostname`); all URLs will be generated
+  appended to this hostname
+Therefore, the following arguments are useful for generating multiple sitemaps
+per Evergreen instance:
+* `--lib-shortname`: limit the list of record URLs to those which have copies
+  owned by the designated library or any of its children;
+* `--prefix`: provides a prefix for the sitemap index file names
+Other options enable you to override the OpenSRF configuration file and the
+database connection credentials, but the default settings are generally fine.
+Note that on very large Evergreen instances, sitemaps can consume hundreds of
+megabytes of disk space, so ensure that your Evergreen instance has enough room
+before running the script.
+Sitemap details
+The sitemap generator script includes located URIs as well as copies
+   listed in the `asset.opac_visible_copies` materialized view, and checks
+   the children or ancestors of the requested libraries for holdings as well.
+To enable search engines to maintain a fresh index of your bibliographic
+records, you may want to include the script in your cron jobs on a nightly or
+weekly basis.
+Sitemap files are generated in the same directory from which the script is
+invoked, so a cron entry will look something like:
+12 2 * * * cd /openils/var/web && /openils/bin/sitemap_generator
index 9a5b9d4..22df88e 100644 (file)
@@ -800,74 +800,3 @@ The system doesn't need the file extension to know what kind of file it is.
 Reload the bib record summary in the web catalog and your new image will display.
-Sitemap generator
-A[sitemap] directs search engines to the pages of
-interest in a web site so that the search engines can intelligently crawl
-your site. In the case of Evergreen, the primary pages of interest are the
-bibliographic record detail pages.
-The sitemap generator script creates sitemaps that adhere to the
- specification, including:
-* limiting the number of URLs per sitemap file to no more than 50,000 URLs;
-* providing the date that the bibliographic record was last edited, so
-  that once a search engine has crawled all of your sites' record detail pages,
-  it only has to reindex those pages that are new or have changed since the last
-  crawl;
-* generating a sitemap index file that points to each of the sitemap files.
-Running the sitemap generator
-The `sitemap_generator` script must be invoked with the following argument:
-* `--lib-hostname`: specifies the hostname for the catalog (for example,
-  `--lib-hostname`); all URLs will be generated
-  appended to this hostname
-Therefore, the following arguments are useful for generating multiple sitemaps
-per Evergreen instance:
-* `--lib-shortname`: limit the list of record URLs to those which have copies
-  owned by the designated library or any of its children;
-* `--prefix`: provides a prefix for the sitemap index file names
-Other options enable you to override the OpenSRF configuration file and the
-database connection credentials, but the default settings are generally fine.
-Note that on very large Evergreen instances, sitemaps can consume hundreds of
-megabytes of disk space, so ensure that your Evergreen instance has enough room
-before running the script.
-To enable search engines to maintain a fresh index of your bibliographic
-records, you may want to include the script in your cron jobs on a nightly or
-weekly basis.
-Sitemap files are generated in the same directory from which the script is
-invoked, so a cron entry will look something like:
-12 2 * * * cd /openils/var/web && /openils/bin/sitemap_generator
-Troubleshooting TPAC errors
-If there is a problem such as a TT syntax error, it generally shows up as an
-ugly server failure page. If you check the Apache error logs, you will probably
-find some solid clues about the reason for the failure. For example, in the
-following example, the error message identifies the file in which the problem
-occurred as well as the relevant line numbers.
-Example error message in Apache error logs:
-bash# grep "template error" /var/log/apache2/error_log
-[Tue Dec 06 02:12:09 2011] [warn] [client] egweb: template error:
- file error - parse error - opac/parts/record/summary.tt2 line 112-121:
-  unexpected token (!=)\n  [% last_cn = 0;\n        FOR copy_info IN
-  ctx.copies;\n            callnum = copy_info.call_number_label;\n
diff --git a/docs/admin_initial_setup/troubleshooting_tpac.adoc b/docs/admin_initial_setup/troubleshooting_tpac.adoc
new file mode 100644 (file)
index 0000000..5835171
--- /dev/null
@@ -0,0 +1,19 @@
+Troubleshooting TPAC errors
+If there is a problem such as a TT syntax error, it generally shows up as an
+ugly server failure page. If you check the Apache error logs, you will probably
+find some solid clues about the reason for the failure. For example, in the
+following example, the error message identifies the file in which the problem
+occurred as well as the relevant line numbers.
+Example error message in Apache error logs:
+bash# grep "template error" /var/log/apache2/error_log
+[Tue Dec 06 02:12:09 2011] [warn] [client] egweb: template error:
+ file error - parse error - opac/parts/record/summary.tt2 line 112-121:
+  unexpected token (!=)\n  [% last_cn = 0;\n        FOR copy_info IN
+  ctx.copies;\n            callnum = copy_info.call_number_label;\n
diff --git a/docs/opac/sitemap.adoc b/docs/opac/sitemap.adoc
new file mode 100644 (file)
index 0000000..e65663d
--- /dev/null
@@ -0,0 +1,18 @@
+Sitemap generator
+A[sitemap] directs search engines to the pages of
+interest in a web site so that the search engines can intelligently crawl
+your site. In the case of Evergreen, the primary pages of interest are the
+bibliographic record detail pages.
+The sitemap generator script creates sitemaps that adhere to the
+ specification, including:
+* limiting the number of URLs per sitemap file to no more than 50,000 URLs;
+* providing the date that the bibliographic record was last edited, so
+  that once a search engine has crawled all of your sites' record detail pages,
+  it only has to reindex those pages that are new or have changed since the last
+  crawl;
+* generating a sitemap index file that points to each of the sitemap files.
diff --git a/docs/opac/visibility_on_the_web.adoc b/docs/opac/visibility_on_the_web.adoc
new file mode 100644 (file)
index 0000000..0ed5c53
--- /dev/null
@@ -0,0 +1,123 @@
+Library visibility on the Web
+Evergreen follows a number of best practices to
+make Library data integrate with the rest of the
+Web.  Evergreen's public catalog pages are
+designed so that search engines can easily extract
+meaningful information about your library and
+collections.  Evergreen is also preparing for an
+eventual shift toward linked open bibliographic
+Catalog data in search engines
+Each record in the catalog is displayed to search
+engines using[] microdata.
+Make sure your system administrator has not added
+a restrictive robots.txt file to your server.
+These files restrict search engines, up to the
+point of not allowing search engines to index your
+site at all.
+Details of the mapping
+ * Each item is listed as a
+[schema:Offer], which is
+   the same category that an online bookseller might
+   use to describe an item for sale.  These Offers
+   are always listed with a price of $0.00.
+ * Subject headings are exposed as
+   properties.
+ * Electronic resources are assigned a
+   property, and any notes or link text
+   are assigned a
+   property.
+ * Given a Library of Congress relator code for
+   1xx and 7xx fields, Evergreen surfaces the URL
+   for that relator code along with the
+   property to give machines a better chance
+   of understanding how the person or organization
+   actually contributed to this work.
+ * Linking out to related records:
+   ** Given an LCCN (010 field), Evergreen links to
+      the corresponding Library of Congress record
+      using[schema:sameAs].
+   ** Given an OCLC number (035 field, subfield `a`
+      beginning with `(OCoLC)`), Evergreen links to
+      the corresponding WorldCat record using
+   ** Given a URI (024 field, subfield 2 = `'uri'`),
+      Evergreen links to the corresponding OCLC
+      Work Entity record using
+Viewing microdata
+You can learn more about how Evergreen publicizes
+these data by viewing them directly.  The 
+[structured data linter]
+is a helpful tool for viewing microdata.
+. Using your favorite Web browser, navigate to a
+  record in your public catalog.
+. Copy the URL that displays in your browser's
+  address bar.
+. Go to
+. Under the _Lint by URL_ tab, paste your URL
+  into the text box.
+. Click _Submit_
+Other helpful features for search engines
+ * Titles of catalog pages follow a
+   "Page title - Library name" pattern to provide
+   specific titles in search engine results pages,
+   browser bookmarks, and browser tabs.
+ * Links that robots should not crawl, such as search
+   result links, are marked with the
+   property.
+ * Catalog pages for record details and for library
+   descriptions express a
+   link to simplify the number of variations of page
+   URLs that could otherwise have been derived from
+   different search parameters.
+ * Catalog pages that do not exist return a proper
+   404 "HTTP_NOT_FOUND" HTTP status code, and record
+   detail pages for records that have been deleted
+   now return a proper 410 "HTTP_GONE" HTTP status code.
+ * Record detail and library pages include
+[Open Graph Protocol] markup.
+ * Each library has its own page at
+   _http://localhost/eg/opac/library/LIBRARY_SHORTNAME_
+   that provides machine-readable hours and contact
+   information.
+SKOS support
+Some vocabularies used (or which could be used) for
+stock record attributes and coded value maps in Evergreen
+are published on the web using SKOS. The record
+attributes system can now associate Linked Data URIs
+with specific attribute values. In particular, seed data
+supplying URIs for the RDA Content Type, Media Type, and
+Carrier Type has been added.
+This is an experimental, "under-the-hood" feature that
+will be built upon in subsuquent releases.
index cb046fd..6fea46b 100644 (file)
@@ -104,6 +104,12 @@ include::admin/template_toolkit.adoc[]
 :leveloffset: 0
index d495726..863688f 100644 (file)
@@ -16,7 +16,8 @@ workers in public services roles.
 It is organized into Parts, Chapters, and Sections addressing key
 aspects of the software. 
-Copies of this guide can be accessed in PDF and HTML formats from
+Copies of this guide can be accessed in PDF and HTML formats from
@@ -44,8 +45,15 @@ include::opac/kids_opac.adoc[]
 :leveloffset: 0
+See the Command Line System Administration Manual for details about
+running this script.