From ba4669a9c4936d8c11569558e039b101653b5cc2 Mon Sep 17 00:00:00 2001
From: Andrey Smirnov <Smirnov.Andrey@gmail.com>
Date: Sat, 4 Jul 2015 13:02:33 +0300
Subject: [PATCH] Man page for package display format in search commands. #254

---
 man/aptly.1           | 39 ++++++++++++++++++++++++++++++++++++++-
 man/aptly.1.ronn.tmpl | 21 +++++++++++++++++++++
 2 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/man/aptly.1 b/man/aptly.1
index 0e74e8ca..ae0637fe 100644
--- a/man/aptly.1
+++ b/man/aptly.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "APTLY" "1" "May 2015" "" ""
+.TH "APTLY" "1" "July 2015" "" ""
 .
 .SH "NAME"
 \fBaptly\fR \- Debian repository management tool
@@ -314,6 +314,24 @@ When specified on command line, query may have to be quoted according to shell r
 .P
 \fBaptly repo import percona stable \(cqmysql\-client (>= 3\.6)\(cq\fR
 .
+.SH "PACKAGE DISPLAY FORMAT"
+Some aptly commands (\fBaptly mirror search\fR, \fBaptly package search\fR, \|\.\|\.\|\.) support \fB\-format\fR flag which allows to customize how search results are printed\. Golang templates are used to specify display format, with all package stanza fields available to template\. In addition to package stanza fields aptly provides:
+.
+.TP
+\fBKey\fR
+internal aptly package ID, unique for all packages in aptly (combination of \fBShortKey\fR and \fBFilesHash\fR)\.
+.
+.TP
+\fBFilesHash\fR
+hash that includes MD5 of all packages files\.
+.
+.TP
+\fBShortKey\fR
+package ID, which is unique in single list (mirror, repo, snapshot, \|\.\|\.\|\.), but not unique in whole aptly package collection\.
+.
+.P
+For example, default aptly display format could be presented with the following template: \fB{{\.Package}}_{{\.Version}}_{{\.Architecture}}\fR\. To display package name with dependencies: \fB{{\.Package}} | {{\.Depends}}\fR\. More information on Golang template syntax: http://godoc\.org/text/template
+.
 .SH "GLOBAL OPTIONS"
 .
 .TP
@@ -547,6 +565,10 @@ $ aptly mirror search wheezy\-main \(cq$Architecture (i386), Name (% *\-dev)\(cq
 Options:
 .
 .TP
+\-\fBformat\fR=
+custom format for result printing
+.
+.TP
 \-\fBwith\-deps\fR=false
 include dependencies into search results
 .
@@ -812,6 +834,10 @@ $ aptly repo search my\-software \(cq$Architecture (i386), Name (% *\-dev)\(cq
 Options:
 .
 .TP
+\-\fBformat\fR=
+custom format for result printing
+.
+.TP
 \-\fBwith\-deps\fR=false
 include dependencies into search results
 .
@@ -1102,6 +1128,10 @@ $ aptly snapshot search wheezy\-main \(cq$Architecture (i386), Name (% *\-dev)\(
 Options:
 .
 .TP
+\-\fBformat\fR=
+custom format for result printing
+.
+.TP
 \-\fBwith\-deps\fR=false
 include dependencies into search results
 .
@@ -1518,6 +1548,13 @@ $ aptly package search \(cq$Architecture (i386), Name (% *\-dev)\(cq
 .
 .IP "" 0
 .
+.P
+Options:
+.
+.TP
+\-\fBformat\fR=
+custom format for result printing
+.
 .SH "SHOW DETAILS ABOUT PACKAGES MATCHING QUERY"
 \fBaptly\fR \fBpackage\fR \fBshow\fR \fIpackage\-query\fR
 .
diff --git a/man/aptly.1.ronn.tmpl b/man/aptly.1.ronn.tmpl
index 0ef5389c..fee17971 100644
--- a/man/aptly.1.ronn.tmpl
+++ b/man/aptly.1.ronn.tmpl
@@ -274,6 +274,27 @@ When specified on command line, query may have to be quoted according to shell r
 
   `aptly repo import percona stable 'mysql-client (>= 3.6)'`
 
+## PACKAGE DISPLAY FORMAT
+
+Some aptly commands (`aptly mirror search`, `aptly package search`, ...) support `-format` flag
+which allows to customize how search results are printed. Golang templates are used to specify
+display format, with all package stanza fields available to template. In addition to package stanza
+fields aptly provides:
+
+ * `Key`:
+   internal aptly package ID, unique for all packages in aptly
+   (combination of `ShortKey` and `FilesHash`).
+
+ * `FilesHash`:
+   hash that includes MD5 of all packages files.
+
+ * `ShortKey`:
+   package ID, which is unique in single list (mirror, repo, snapshot, ...), but not unique
+   in whole aptly package collection.
+
+For example, default aptly display format could be presented with the following template:
+`{{"{{"}}.Package{{"}}"}}_{{"{{"}}.Version{{"}}"}}_{{"{{"}}.Architecture{{"}}"}}`. To display package name with dependencies:
+`{{"{{"}}.Package{{"}}"}} | {{"{{"}}.Depends{{"}}"}}`. More information on Golang template syntax: http://godoc.org/text/template
 
 ## GLOBAL OPTIONS