-n, --dry-run option
[mob/metatag] / metatag_doc.lua
1 -- metatag     Metadata extraction utility
2 -- Copyright (C) 2014  Christian Thäter <ct@pipapo.org>
3 --
4 -- This program is free software: you can redistribute it and/or modify
5 -- it under the terms of the GNU General Public License as published by
6 -- the Free Software Foundation, either version 3 of the License, or
7 -- (at your option) any later version.
8 --
9 -- This program is distributed in the hope that it will be useful,
10 -- but WITHOUT ANY WARRANTY; without even the implied warranty of
11 -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 -- GNU General Public License for more details.
13 --
14 -- You should have received a copy of the GNU General Public License
15 -- along with this program.  If not, see <http://www.gnu.org/licenses/>.
16
17 DOC = {}
18
19 DOC.helpsystem = [[
20 HELPSYSTEM
21   The user manual is stored as DOC table within the program itself
22   and accessible with the `-t, --help-topic=topic` option.
23
24   Documentation sections are defined in the DOC table as
25    DOC.section = "string"
26   or using double square brace multiline strings
27
28   Section names starting with a underscore are excluded from the
29   `--help-list` output
30
31 ALLCAPS ON A SINGLE LINE
32   are headers
33
34   Indentation level by a even number is the header/section nesting depth
35    Indentation by a odd number denotes code blocks (not wordwraped).
36
37   Text in %percent% signs gets substituted by the respective sections (stripped
38   off newlines at the begin and end for multiline string handling)
39   When the %percent% substitution was indented by spaces only, then this is retained
40   for all its lines.
41
42 EXAMPLE
43   example above is a title
44
45     this would be a nested section
46      this would be printed as code
47        still in code block because odd indentation
48      end of code block
49
50   Use the source Luke.
51 ]]
52
53
54
55 local function string_interpolate(string, repl, called)
56    called = called or {}
57    return string:gsub("(.-)( *)%%([%w_]+)%%",
58                       function (pre,indent,var)
59                          if not called[var] then
60                             local inter_indent=indent
61                             if #pre == 0 or pre:match("%w$") then
62                                inter_indent = ""
63                             end
64                             called[var] = true
65                             local sub = repl[var] or ("%"..var.."%")
66                             sub = sub:match("^\n?(.-)\n?$") -- remove first and last newline from [[ DOCs
67                             local ret = string_interpolate(indent..string.gsub(sub, "\n", "\n"..inter_indent), repl, called)
68                             called[var] = nil
69                             return pre..ret
70                          end
71                       end
72                    )
73 end
74
75 function getDOC(name)
76    return string_interpolate(DOC[name] or name.." not available", DOC)
77 end
78
79 --[[
80 function DOCtoAsciidoc(text)
81    for line in text:gmatch("([^\n]*)\n?") do
82       if line:match("^%u[%u%s%d]+$") then
83          -- all uppercase is a H1 header
84          io.write(line.."\n")
85          io.write(line:gsub(".", "-").."\n")
86       else
87          io.write(line.."\n")
88       end
89    end
90 end
91 ]]
92
93 function pageDOC(name)
94    page(getDOC(name))
95 end
96
97
98 function listDOC()
99    local skeys={}
100    local text=""
101    for section in pairs(DOC) do
102       table.insert(skeys, section)
103    end
104
105    table.sort(skeys)
106    for i=1,#skeys do
107       if skeys[i][1] ~= '_' then
108          text = text.."    "..skeys[i].."\n"
109       end
110    end
111    return text
112 end
113
114
115 DOC.functions = ""
116 DOC.genopts = ""
117 DOC.engines = ""
118 DOC.exporters = ""
119
120 DOC.license = [[
121 metatag             Metadata extraction utility
122 Copyright (C) 2014  Christian Thäter <ct@pipapo.org>
123
124 This program is free software: you can redistribute it and/or modify
125 it under the terms of the GNU General Public License as published by
126 the Free Software Foundation, either version 3 of the License, or
127 (at your option) any later version.
128
129 This program is distributed in the hope that it will be useful,
130 but WITHOUT ANY WARRANTY; without even the implied warranty of
131 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
132 GNU General Public License for more details.
133
134 You should have received a copy of the GNU General Public License
135 along with this program.  If not, see <http://www.gnu.org/licenses/>.
136 ]]
137
138
139 DOC.manual = [[
140 %version% %_usage%
141
142 %_manual%
143 ]]
144
145 DOC._manual = [[
146 OPTIONS SUMMARY
147   %_options_summary%
148
149 DESCRIPTION
150   %processing%
151
152 OPTIONS
153   %options%
154
155 CONFIGFILES
156   %configfiles%
157
158 DEFINED ENGINES CALLED BY RULES
159   The current `metatag` has following engines defined:
160
161   %engines%
162
163 EXPORTERS
164   %exporters%
165
166
167 EXTENDING
168   metatag can be extended by supplying extra rules, engines and exporters as lua scripts.
169   Either in the common config file locations (see above) or with the -l/--load option.
170
171   %_meta%
172
173 FUNCTIONS
174   metatag defines some global functions which can be used in custom rules, engines and exporters
175
176   %functions%
177
178 CONTRIBUTING
179   %contributing%
180
181 LICENSE
182   %license%
183
184 SUPPORT
185   %_bugs%
186
187   There is a mailinglist for the project, you can subscribe at
188    http://lists.pipapo.org/cgi-bin/mailman/listinfo/metatag
189   or by sending mail to
190    mailto:metatag-request@lists.pipapo.org?subject=subscribe
191 ]]
192
193
194 DOC.processing = [[
195 metatag is driven by rules reacting metadata disovered. Processing starts by
196 adding '/=path' for each path given as argument to the program. Which will
197 trigger the matching rule calling the 'stat' engine whose adds more metadata and in
198 turn matching more rules calling further engines and so on.
199
200 Rules are defined with either the 'field=value' or 'field~=value' operator and provide
201 a list of engines to call upon a successful match. Rules are ordered in sequence of
202 their appearence which can be important because some rules may abort processing or rely
203 on metadata added earlier.
204
205 Normally it is ensured that each engine is only called once per file, but each engine
206 can override this.
207
208 When no more Rules match anymore and all engines are run then the given exporters are
209 called with the gathered metadata. The user may provide some filtering to each exporter
210 to control what metadata actually gets exported.
211 ]]
212
213
214 --DOC.tutorial = [[
215 --
216 --]]
217
218 DOC.options = [[
219 -l, --load=file
220   Load a lua file (additional engines, rules, exporters). Loaded before configfiles and the rules, engines
221   and exporters shipped with the program to allow one to override rules by custom configuration.
222
223 -e, --lua=code
224   Execute some inline lua code (additional engines, rules, exporters). Loaded before `--load`. configfiles and the
225   rules, engines and exporters shipped with the program to allow one to override rules by custom configuration.
226
227 -v, --verbose
228   Enables verbose messages on which report about initialization (adding rules, engines and exporters)
229   and what tools are called when progressing.
230
231 -q, --quiet
232   Disables all messages.
233
234 -d, --debug
235   Enable debug messages on which give detailed messages about progress. Which rules match and
236   what engines and exporters are called.
237
238 -O, --option=key[[-]=value][,..]
239   Generic options are stored in a global 'options' table and can be evaluated by any lua file
240   loaded at runtime (additional rules, engines, exporters). Default options can also be cleared.
241   Options are separated by commas, each one may assign (or clear) a value with the = (-=) operators.
242   when no operator and value is given then option is just set to 'true'. Generic options are
243   extensible custom rules, engines and exporters may query new ones and should document them.
244   Currently available are:
245
246   %genopts%
247
248 --no-buildinrules
249   do not load the rules shipped with metatag.
250
251 --no-configfiles
252   do not load the default configfiles "$HOME/.metatag.lua", "$HOME/.config/metatag.lua" and "./.metatag.lua".
253
254 -n, --dry-run
255   Loads all config files but don't process files. Useful to check for syntax errors in custom written
256   files.
257
258 -r, --recursive
259   short for --option=recursive which activates the rule to descend into subdirectories
260
261 -x, --exclude=patterns
262   The given patterns must be a comma separated list of rule patterns, for each of the given pattern an
263   exclude rule is added which aborts processing the matching file. See 'metatag -t lua_patterns' to learn
264   about the lua string pattern syntax.
265
266 -o, --export=exporter[:specs..][,...]
267   Select one or more exporters separated by commas. When none is given then the 'print' exporter is selected.
268   Each exporter can have a colon separated list of specs in the field=value form to filter the exported
269   metadata. When a spec is prepended by a minus sign then the match is inverted. Filtering stops at the first
270   found match, when no match is found then the metadata is not included in the export. By default ':-^/$=:'
271   are appended to the specs list. That is the initial '/=filename' metadata is filtered out but anything
272   else is included.
273
274 -V, --version
275   Display version information, then exit
276
277 -h, --help
278   Display help, then exit
279
280 -t, --help-topic=topic
281   Display long help about topic
282
283 --help-list
284   List available help topics of the buildin help system. Each topic can be read with the -t option above.
285 ]]
286
287
288
289
290 DOC.contributing = [[
291 Metatag is free software maintained in a git repository at
292
293  git://git.pipapo.org/metatag
294
295 You always find the newest version there.
296
297 This project lives from the varity of engines and rules available. One can easily add new facilities.
298 To make it easy to get contributions into the mainline there is an open (untrusted) mob repository
299 where anyone can push changes to. When you do so please open your own branch on the mob repository
300 and notify the maintainer and users about your contribution. When acceptable things will be merged ASAP.
301 This mob repository is available as
302
303  git://git.pipapo.org/mob/metatag
304
305 Please note that anyone can push malicious code there, do NOT run the code without review.
306 ]]
307
308 -- borrowed from the lua reference manual, shouls be ok with the MIT license
309 DOC.lua_patterns = [[
310 LUA PATTERNS
311   Character Class:
312
313   A character class is used to represent a set of characters. The following combinations are allowed in describing a character class:
314
315    x
316     (where x is not one of the magic characters ^$()%.[]*+-?) represents the character x itself.
317
318    .
319     (a dot) represents all characters.
320
321    %a
322     represents all letters.
323
324    %c
325     represents all control characters.
326
327    %d
328     represents all digits.
329
330    %g
331     represents all printable characters except space.
332
333    %l
334     represents all lowercase letters.
335
336    %p
337     represents all punctuation characters.
338
339    %s
340     represents all space characters.
341
342    %u
343     represents all uppercase letters.
344
345    %w
346     represents all alphanumeric characters.
347
348    %x
349     represents all hexadecimal digits.
350
351    %x
352     (where x is any non-alphanumeric character) represents the character x.
353     This is the standard way to escape the magic characters. Any punctuation character (even the non magic)
354     can be preceded by a '%' when used to represent itself in a pattern.
355
356    [set]
357     represents the class which is the union of all characters in set. A range of characters can be specified
358     by separating the end characters of the range, in ascending order, with a '-', All classes %x described
359     above can also be used as components in set. All other characters in set represent themselves. For example,
360     [%w_] (or [_%w]) represents all alphanumeric characters plus the underscore, [0-7] represents the octal digits,
361     and [0-7%l%-] represents the octal digits plus the lowercase letters plus the '-' character.
362
363     The interaction between ranges and classes is not defined. Therefore, patterns like [%a-z] or [a-%%] have no meaning.
364
365    [^set]
366     represents the complement of set, where set is interpreted as above.
367
368   For all classes represented by single letters (%a, %c, etc.), the corresponding uppercase letter represents the
369   complement of the class. For instance, %S represents all non-space characters.
370
371   The definitions of letter, space, and other character groups depend on the current locale. In particular,
372   the class [a-z] may not be equivalent to %l.
373
374   Pattern Item:
375
376   A pattern item can be
377
378     - a single character class, which matches any single character in the class;
379     - a single character class followed by '*', which matches 0 or more repetitions of characters in the class.
380       These repetition items will always match the longest possible sequence;
381     - a single character class followed by '+', which matches 1 or more repetitions of characters in the class.
382       These repetition items will always match the longest possible sequence;
383     - a single character class followed by '-', which also matches 0 or more repetitions of characters in the class.
384       Unlike '*', these repetition items will always match the shortest possible sequence;
385     - a single character class followed by '?', which matches 0 or 1 occurrence of a character in the class;
386     - %n, for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below);
387     - %bxy, where x and y are two distinct characters; such item matches strings that start with x, end with y,
388       and where the x and y are balanced. This means that, if one reads the string from left to right, counting +1
389       for an x and -1 for a y, the ending y is the first y where the count reaches 0. For instance, the item %b()
390       matches expressions with balanced parentheses.
391     - %f[set], a frontier pattern; such item matches an empty string at any position such that the next character
392       belongs to set and the previous character does not belong to set. The set set is interpreted as previously described.
393       The beginning and the end of the subject are handled as if they were the character '\0'.
394
395   Pattern:
396
397   A pattern is a sequence of pattern items. A caret '^' at the beginning of a pattern anchors the match at the beginning of the subject string.
398   A '$' at the end of a pattern anchors the match at the end of the subject string.
399   At other positions, '^' and '$' have no special meaning and represent themselves.
400
401   Captures:
402
403   A pattern can contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds,
404   the substrings of the subject string that match captures are stored (captured) for future use.
405   Captures are numbered according to their left parentheses. For instance, in the pattern "(a*(.)%w(%s*))",
406   the part of the string matching "a*(.)%w(%s*)" is stored as the first capture (and therefore has number 1);
407   the character matching "." is captured with number 2, and the part matching "%s*" has number 3.
408
409   As a special case, the empty capture () captures the current string position (a number). For instance,
410   if we apply the pattern "()aa()" on the string "flaaap", there will be two captures: 3 and 5.
411 ]]
412
413 DOC._installation = [[
414 Metatag comes with install script, to install it use
415   sh metatag.install
416
417 Everything gets installed under `/usr/local` but one can overide the following variables
418
419  prefix
420   root of the installation
421   defaults to `/usr/local/`
422
423  bindir
424   where to place the `metatag` executable
425   defaults to `$prefix/bin/`
426
427  pkgdir
428   where the lua scripts are installed
429   defaults to `$prefix/share/metatag/`
430
431 Dependencies:
432
433 Metatag is written in lua, the install script checks that either luajit, lua5.1, lua, or lua5.2 is available.
434 Luarocks is optional and loaded when available, thus lua packages could be installed with the OS/Distribution
435 package manager or luarocks.
436
437 Further it makes use of the lua-stdlib and nixio. Both are available through luarocks at least.
438 The installer checks the presence of these libs but not if the installed version is sufficient (TBD)
439
440 The engines and exporters need some external programs , these external dependencies are always
441 somewhat in flux and engines will report at runtime when a programm is not found.
442
443 currently the following programs are suggested:
444
445  xdg-utils
446  file
447  coreutils
448  mplayer
449  exiftags
450  git-annex
451 ]]
452
453 DOC._README = [[
454 %version%
455
456 INSTALLATION
457   %_installation%
458
459 MANUAL
460   %_usage%
461
462 %_manual%
463 ]]
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484 DOC._attic_help_rules = [[
485       about helpsystem
486       about engines
487 ]]
488
489 DOC._attic_help_rules = [[
490 RULES
491  Exclude
492
493 ]]
494
495 DOC._attic_help_engines = [[
496 ENGINES
497  PRE
498  POST
499
500
501 returns "break" "multi"
502 ]]
503
504 DOC._attic_help_exporters = [[
505 EXPORTERS
506 exporter receives a copy
507 specs exclude is -
508 _metadata
509 ]]