From: Michael Tremer <michael.tremer@ipfire.org>
Date: Tue, 22 Oct 2019 10:24:33 +0000 (+0100)
Subject: location: Add a "How to use" page
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=55eea0982ecb04c75d8b1a4f9236b50f77a0d8ef;p=ipfire.org.git

location: Add a "How to use" page

Signed-off-by: Michael Tremer <michael.tremer@ipfire.org>
---

diff --git a/Makefile.am b/Makefile.am
index a50e5847..c1e02ec3 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -181,6 +181,7 @@ templates_fireinfo_modulesdir = $(templates_fireinfodir)/modules
 templates_location_DATA = \
 	src/templates/location/base.html \
 	src/templates/location/blacklists.html \
+	src/templates/location/how-to-use.html \
 	src/templates/location/index.html \
 	src/templates/location/lookup.html
 
@@ -910,10 +911,12 @@ static_images_DATA = \
 	src/static/img/apple-touch-icon-76x76-precomposed.png \
 	src/static/img/apple-touch-icon-72x72-precomposed.png \
 	src/static/img/apple-touch-icon-60x60-precomposed.png \
+	src/static/img/bash-logo.svg \
 	src/static/img/default-avatar.jpg \
 	src/static/img/ipfire-tux.png \
 	src/static/img/iuse-not-found.png \
-	src/static/img/lightningwirelabs-logo.svg
+	src/static/img/lightningwirelabs-logo.svg \
+	src/static/img/python-logo.svg
 
 static_imagesdir = $(staticdir)/img
 
diff --git a/src/scss/style.scss b/src/scss/style.scss
index 0da1d000..401590f1 100644
--- a/src/scss/style.scss
+++ b/src/scss/style.scss
@@ -80,6 +80,11 @@ pre {
 		background-color: inherit;
 		padding: 0;
 	}
+
+	&.pre-light {
+		background-color: $white;
+		color: $body-bg;
+	}
 }
 
 .card {
diff --git a/src/static/img/bash-logo.svg b/src/static/img/bash-logo.svg
new file mode 100644
index 00000000..2fb24a3c
--- /dev/null
+++ b/src/static/img/bash-logo.svg
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 22.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 150 150" style="enable-background:new 0 0 150 150;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#FFFFFF;}
+	.st1{fill:#2A3238;}
+	.st2{fill:#4DA925;}
+</style>
+<g>
+	<g>
+		<path class="st0" d="M118.9,40.3L81.7,18.2c-4.4-2.6-9.9-2.6-14.4,0L30.1,40.3c-4.4,2.6-7.2,7.5-7.2,12.8v44.2
+			c0,5.3,2.7,10.1,7.2,12.8l37.2,22.1c2.2,1.3,4.7,2,7.2,2s5-0.7,7.2-2l37.2-22.1c4.4-2.6,7.2-7.5,7.2-12.8V53
+			C126.1,47.8,123.4,42.9,118.9,40.3z"/>
+	</g>
+	<g>
+		<g>
+			<path class="st1" d="M118.9,40.3L81.7,18.2c-2.2-1.3-4.7-2-7.2-2s-5,0.7-7.2,2L30.1,40.3c-4.4,2.6-7.2,7.5-7.2,12.8v44.2
+				c0,5.3,2.7,10.1,7.2,12.8l37.2,22.1c2.2,1.3,4.7,2,7.2,2s5-0.7,7.2-2l37.2-22.1c4.4-2.6,7.2-7.5,7.2-12.8V53
+				C126.1,47.8,123.4,42.9,118.9,40.3z M68.6,129.8l-37.2-22.1c-3.6-2.2-5.9-6.2-5.9-10.5V53c0-4.3,2.3-8.4,5.9-10.5l37.2-22.1
+				c1.8-1.1,3.8-1.6,5.9-1.6c2.1,0,4.1,0.6,5.9,1.6l37.2,22.1c3.1,1.8,5.1,5,5.7,8.5c-1.2-2.6-4-3.4-7.3-1.5L80.9,71.3
+				c-4.4,2.6-7.6,5.4-7.6,10.7v43.4c0,3.2,1.3,5.2,3.2,5.8c-0.6,0.1-1.3,0.2-2,0.2C72.5,131.5,70.4,130.9,68.6,129.8z"/>
+		</g>
+	</g>
+	<g>
+		<path class="st2" d="M109.2,101.5l-9.3,5.5c-0.2,0.1-0.4,0.3-0.4,0.6v2.4c0,0.3,0.2,0.4,0.4,0.3l9.4-5.7c0.2-0.1,0.3-0.4,0.3-0.7
+			v-2.1C109.6,101.5,109.4,101.4,109.2,101.5z"/>
+	</g>
+	<g>
+		<path class="st0" d="M89.4,81.1c0.3-0.2,0.5,0,0.6,0.4v3.2c1.3-0.5,2.5-0.7,3.6-0.4c0.2,0.1,0.3,0.4,0.2,0.7l-0.7,2.8
+			c-0.1,0.2-0.2,0.4-0.3,0.6c-0.1,0.1-0.1,0.1-0.2,0.1s-0.2,0.1-0.3,0c-0.5-0.1-1.6-0.4-3.4,0.6c-1.9,1-2.6,2.6-2.5,3.8
+			c0,1.5,0.8,1.9,3.3,1.9c3.4,0.1,4.9,1.6,5,5c0,3.4-1.8,7.1-4.6,9.3l0.1,3.2c0,0.4-0.2,0.8-0.5,1l-1.9,1.1c-0.3,0.2-0.5,0-0.6-0.4
+			v-3.1c-1.6,0.7-3.2,0.8-4.3,0.4c-0.2-0.1-0.3-0.4-0.2-0.7l0.7-2.9c0.1-0.2,0.2-0.5,0.3-0.6c0.1-0.1,0.1-0.1,0.2-0.1
+			c0.1-0.1,0.2-0.1,0.3,0c1.1,0.4,2.6,0.2,3.9-0.5c1.8-0.9,2.9-2.7,2.9-4.5c0-1.6-0.9-2.3-3-2.3c-2.7,0-5.2-0.5-5.3-4.5
+			c0-3.3,1.7-6.7,4.4-8.8v-3.2c0-0.4,0.2-0.8,0.5-1L89.4,81.1z"/>
+	</g>
+</g>
+</svg>
diff --git a/src/static/img/python-logo.svg b/src/static/img/python-logo.svg
new file mode 100644
index 00000000..366f52f3
--- /dev/null
+++ b/src/static/img/python-logo.svg
@@ -0,0 +1,113 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://web.resource.org/cc/"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="110.4211"
+   height="109.8461"
+   id="svg2169"
+   sodipodi:version="0.32"
+   inkscape:version="0.45.1"
+   version="1.0"
+   sodipodi:docbase="/home/bene/Desktop"
+   sodipodi:docname="dessin-1.svg"
+   inkscape:output_extension="org.inkscape.output.svg.inkscape">
+  <defs
+     id="defs2171">
+    <linearGradient
+       id="linearGradient11301"
+       inkscape:collect="always">
+      <stop
+         id="stop11303"
+         offset="0"
+         style="stop-color:#ffe052;stop-opacity:1" />
+      <stop
+         id="stop11305"
+         offset="1"
+         style="stop-color:#ffc331;stop-opacity:1" />
+    </linearGradient>
+    <linearGradient
+       gradientUnits="userSpaceOnUse"
+       y2="168.1012"
+       x2="147.77737"
+       y1="111.92053"
+       x1="89.136749"
+       id="linearGradient11307"
+       xlink:href="#linearGradient11301"
+       inkscape:collect="always" />
+    <linearGradient
+       id="linearGradient9515"
+       inkscape:collect="always">
+      <stop
+         id="stop9517"
+         offset="0"
+         style="stop-color:#387eb8;stop-opacity:1" />
+      <stop
+         id="stop9519"
+         offset="1"
+         style="stop-color:#366994;stop-opacity:1" />
+    </linearGradient>
+    <linearGradient
+       gradientUnits="userSpaceOnUse"
+       y2="131.85291"
+       x2="110.14919"
+       y1="77.070274"
+       x1="55.549179"
+       id="linearGradient9521"
+       xlink:href="#linearGradient9515"
+       inkscape:collect="always" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.24748737"
+     inkscape:cx="-260.46312"
+     inkscape:cy="316.02744"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     width="131.10236px"
+     height="184.25197px"
+     inkscape:window-width="872"
+     inkscape:window-height="624"
+     inkscape:window-x="5"
+     inkscape:window-y="48" />
+  <metadata
+     id="metadata2174">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Calque 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-473.36088,-251.72485)">
+    <g
+       id="g1894"
+       transform="translate(428.42338,184.2561)">
+      <path
+         style="opacity:1;color:#000000;fill:url(#linearGradient9521);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible"
+         d="M 99.75,67.46875 C 71.718268,67.468752 73.46875,79.625 73.46875,79.625 L 73.5,92.21875 L 100.25,92.21875 L 100.25,96 L 62.875,96 C 62.875,96 44.9375,93.965724 44.9375,122.25 C 44.937498,150.53427 60.59375,149.53125 60.59375,149.53125 L 69.9375,149.53125 L 69.9375,136.40625 C 69.9375,136.40625 69.433848,120.75 85.34375,120.75 C 101.25365,120.75 111.875,120.75 111.875,120.75 C 111.875,120.75 126.78125,120.99096 126.78125,106.34375 C 126.78125,91.696544 126.78125,82.125 126.78125,82.125 C 126.78125,82.124998 129.04443,67.46875 99.75,67.46875 z M 85,75.9375 C 87.661429,75.937498 89.8125,78.088571 89.8125,80.75 C 89.812502,83.411429 87.661429,85.5625 85,85.5625 C 82.338571,85.562502 80.1875,83.411429 80.1875,80.75 C 80.187498,78.088571 82.338571,75.9375 85,75.9375 z "
+         id="path8615" />
+      <path
+         id="path8620"
+         d="M 100.5461,177.31485 C 128.57784,177.31485 126.82735,165.1586 126.82735,165.1586 L 126.7961,152.56485 L 100.0461,152.56485 L 100.0461,148.7836 L 137.4211,148.7836 C 137.4211,148.7836 155.3586,150.81787 155.3586,122.53359 C 155.35861,94.249323 139.70235,95.252343 139.70235,95.252343 L 130.3586,95.252343 L 130.3586,108.37734 C 130.3586,108.37734 130.86226,124.03359 114.95235,124.03359 C 99.042448,124.03359 88.421098,124.03359 88.421098,124.03359 C 88.421098,124.03359 73.514848,123.79263 73.514848,138.43985 C 73.514848,153.08705 73.514848,162.6586 73.514848,162.6586 C 73.514848,162.6586 71.251668,177.31485 100.5461,177.31485 z M 115.2961,168.8461 C 112.63467,168.8461 110.4836,166.69503 110.4836,164.0336 C 110.4836,161.37217 112.63467,159.2211 115.2961,159.2211 C 117.95753,159.2211 120.1086,161.37217 120.1086,164.0336 C 120.10861,166.69503 117.95753,168.8461 115.2961,168.8461 z "
+         style="opacity:1;color:#000000;fill:url(#linearGradient11307);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible" />
+    </g>
+  </g>
+</svg>
diff --git a/src/templates/base.html b/src/templates/base.html
index 568b8b7f..55086919 100644
--- a/src/templates/base.html
+++ b/src/templates/base.html
@@ -153,6 +153,12 @@
 
 						<div class="collapse navbar-collapse" id="navbar">
 							<ul class="navbar-nav ml-auto">
+								<li class="nav-item">
+									<a class="nav-link {% if request.path == "/how-to-use" %}active{% end %}" href="/how-to-use">
+										{{ _("How To Use") }}
+									</a>
+								</li>
+
 								<li class="nav-item">
 									<a class="nav-link {% if request.path == "/download" %}active{% end %}" href="/download">
 										{{ _("Download") }}
diff --git a/src/templates/location/how-to-use.html b/src/templates/location/how-to-use.html
new file mode 100644
index 00000000..975dfc11
--- /dev/null
+++ b/src/templates/location/how-to-use.html
@@ -0,0 +1,123 @@
+{% extends "../base.html" %}
+
+{% block title %}{{ _("How To Use") }}{% end block %}
+
+{% block container %}
+	<section>
+		<div class="container">
+			<div class="row">
+				<div class="col col-lg-6">
+					<h1 class="display-2">{{ _("How To Use") }}</h1>
+
+					<p>
+						<code>libloc</code> is versatile, fast and easy to use
+						in any application.
+					</p>
+				</div>
+			</div>
+		</div>
+	</section>
+
+	<section class="inverse">
+		<div class="container">
+			<div class="row justify-content-between flex-md-row-reverse">
+				<div class="col-12 col-md-4 text-center text-md-right">
+					<img class="img-fluid w-100 my-5" src="{{ static_url("img/bash-logo.svg") }}"
+						alt="{{ _("CLI") }}">
+				</div>
+
+				<div class="col-12 col-md-8">
+					<h1>{{ _("Command Line") }}</h1>
+
+					<p>
+						<code>libloc</code> comes with a command line tool which
+						makes it easy to test the library or integrate it into
+						your shell scripts.
+						<code>location-query(8)</code> knows a couple of commands
+						to retrieve country or Autonomous System of an IP address
+						and can generate lists of networks to be imported into
+						other software.
+					</p>
+
+					<p>
+						Although this is not the fastest way to lookup a large number
+						of IP addresses, <code>location-query(8)</code> is versatile
+						and very easy to use.
+					</p>
+
+					<a class="btn btn-secondary" href="https://man-pages.ipfire.org/libloc/location-query.html">
+						{{ _("Man Page") }}
+					</a>
+				</div>
+			</div>
+
+			<div class="row">
+				<div class="col-12">
+					<h6>{{ _("Search for an Autonomous System by Name") }}</h6>
+
+					<pre class="mb-4"><code>$ location-query search-as "Lightning Wire Labs"
+AS204867 (Lightning Wire Labs GmbH)</code></pre>
+
+					<h6>{{ _("Lookup an IP Address") }}</h6>
+
+					<pre class="mb-4"><code>$ location-query -d test.db lookup 81.3.27.38
+81.3.27.38 belongs to 81.3.27.0/24 which is a part of AS24679 (Hostway Deutschland GmbH)</code></pre>
+				</div>
+			</div>
+		</div>
+	</section>
+
+	<section>
+		<div class="container">
+			<div class="row justify-content-between flex-md-row-reverse">
+				<div class="col-12 col-md-4 text-center text-md-right">
+					<img class="img-fluid w-100 my-5" src="{{ static_url("img/python-logo.svg") }}"
+						alt="{{ _("Python") }}">
+				</div>
+
+				<div class="col-12 col-md-6">
+					<h1>{{ _("Python") }}</h1>
+
+					<p>
+						<code>libloc</code> comes with native Python bindings which
+						are used by its main command-line tool
+						<a class="text-white" href="https://man-pages.ipfire.org/libloc/location-query.html">
+							<code>location-query</code>
+						</a>.
+						They are the most advanced bindings as they support reading
+						from the database as well as writing to it.
+					</p>
+				</div>
+			</div>
+
+			<div class="row">
+				<div class="col-12">
+					<h6>{{ _("Load the database") }}</h6>
+
+					<pre class="pre-light mb-4"><code>Python 3.7.3 (default, Apr  3 2019, 05:39:12)
+[GCC 8.3.0] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+&gt;&gt;&gt; import location
+&gt;&gt;&gt; d = location.Database("/usr/share/location/database.db")</code></pre>
+
+					<h6>{{ _("Search for an Autonomous System by Name") }}</h6>
+
+					<pre class="pre-light mb-4"><code>&gt;&gt;&gt; for i in d.search_as("Lightning Wire Labs"):
+...   print(i)
+...
+AS204867 (Lightning Wire Labs GmbH)</code></pre>
+
+					<h6>{{ _("Lookup an IP Address") }}</h6>
+
+					<pre class="pre-light"><code>&gt;&gt;&gt; n = d.lookup("81.3.27.38")
+&gt;&gt;&gt; n
+&lt;location.Network 81.3.27.0/24&gt;
+&gt;&gt;&gt; n.asn
+24679
+&gt;&gt;&gt; n.country_code
+'DE'</code></pre>
+				</div>
+			</div>
+		</div>
+	</section>
+{% end block %}
diff --git a/src/templates/location/index.html b/src/templates/location/index.html
index 11882941..763a1759 100644
--- a/src/templates/location/index.html
+++ b/src/templates/location/index.html
@@ -64,8 +64,8 @@
 					</p>
 
 					<div class="btn-toolbar mb-5">
-						<a class="btn btn-primary mr-2" href="/download">{{ _("Download") }}</a>
-						<a class="btn btn-secondary" href="https://www.ipfire.org/donate">
+						<a class="btn btn-secondary mr-2" href="/how-to-use">{{ _("How To Use") }}</a>
+						<a class="btn btn-primary" href="https://www.ipfire.org/donate">
 							<span class="fas fa-heart"></span>  {{ _("Donate") }}
 						</a>
 					</div>
diff --git a/src/web/__init__.py b/src/web/__init__.py
index ff7cd400..53fc896b 100644
--- a/src/web/__init__.py
+++ b/src/web/__init__.py
@@ -250,6 +250,7 @@ class Application(tornado.web.Application):
 		# location.ipfire.org
 		self.add_handlers(r"location(\.dev)?\.ipfire\.org", [
 			(r"/", location.IndexHandler),
+			(r"/how\-to\-use", StaticHandler, { "template" : "../location/how-to-use.html" }),
 			(r"/lookup/(.+)/blacklists", location.BlacklistsHandler),
 			(r"/lookup/(.+)", location.LookupHandler),
 		])