Send Motion-user mailing list submissions to
[email protected]
To subscribe or unsubscribe via the World Wide Web, visit
https://lists.sourceforge.net/lists/listinfo/motion-user
or, via email, send a message with subject or body 'help' to
[email protected]
You can reach the person managing the list at
[email protected]
When replying, please edit your Subject line so it is more specific
than "Re: Contents of Motion-user digest..."
Today's Topics:
1. Re: How the documentation on the Motion wiki is working
(Kenneth Lavrsen)
----------------------------------------------------------------------
Message: 1
Date: Fri, 5 Aug 2016 23:21:07 +0200
From: Kenneth Lavrsen <[email protected]>
Subject: Re: [Motion-user] How the documentation on the Motion wiki is
working
To: Motion discussion list <[email protected]>
Message-ID: <[email protected]>
Content-Type: text/plain; charset="us-ascii"
I forgot to write
And now the man page
In front of the section that starts with "it is a bit hidden"
> On 05 Aug 2016, at 23:07, Kenneth Lavrsen <[email protected]> wrote:
>
> Hi all
>
> Let me introduce what is under the hood of the project documentation of Motion
>
> Ignore all the bug report, feature request, patch features. They are awful
> and could be implemented much better but there is no point that I try to do
> that because Github offers the same out of the box in a familiar and
> superiour way.
>
> But on the documentation side the Foswiki features are pretty cool and not at
> all supported by Github or Sourceforge
>
> You probably all know the Motion guide.
>
> You go to http://www.lavrsen.dk/foswiki/bin/view/Motion/WebHome. You click in
> the Motion Guide and you land on
> http://www.lavrsen.dk/foswiki/bin/view/Motion/MotionGuide
>
> From there you have several choices.
>
> The first is the Installation. And if you ever try to edit that page it has a
> short text and then followed by
>
> %TOC%
>
> %INCLUDE{"MotionOverview"}%
> %INCLUDE{"KnownProblems"}%
> %INCLUDE{"InstallOverview"}%
> %INCLUDE{"PrepareInstall"}%
> %INCLUDE{"ConfigureScript"}%
> %INCLUDE{"MakeInstall"}%
> %INCLUDE{"UpgradingFromOlderVersion"}%
> %INCLUDE{"ErrorLogging"}%
>
> All the %SOMETHING% are macros. %TOC% is a table of content. And %INCLUDE....
> simply includes pages. So all it is is a modular approach so you do not have
> to sit and edit an evil long page. So to edit the documentation you go to the
> sub page and start typing.
>
> The markup language is simple.
>
> ---+ Headline level 1
>
> ---++ Headline level 2
>
> ---+++ Headline level 3
>
> Some *bold* text.
> WikiWords like WoW, HitMeGood etc automatically link to a page with that
> name. WikiWord starts with upper case followed by lower case followed by
> uppercase and you have a WikiWord.
> WikiWord
>
> Notawikiword (not capitals in the middle)
> notAwikiWord (does not start with a capital)
>
> Wiki2Word is a wikiword because number count as lower case.
>
> ALSoaWikiWord2Go - Also a wiki word. The minute the parser saw ALSoaW it
> because a wiki word.
>
> If the page exists it links to it. If the page does not exist it suggest that
> you create it.
>
> !IDoNotWantThisAsWikiWord is not a wikiword. The ! cancels the wikiword-ness
> but the ! is invisible.
>
> There are two edit modes. Normal Edit is a WYSIWYG editor which is OK. Edit
> Wikitext is for us geeks that want to control what we do. If you edit
> existing text you quickly see how it works
>
> Tables use the syntax
>
> | *Heading text* | *Second Heading* |
> | text here | more cell text here |
> | hello | here I am |
>
> Very simple.
> Back to the documentation
>
> Getting It Running is also a bunch of includes. Some are pretty smart and
> intelligent.
>
> Like the table of options. Noone had written that table.
> The table gets generated in the included page ConfigFileOptions (
> http://www.lavrsen.dk/foswiki/bin/view/Motion/ConfigFileOptions )
>
> It has code that looks like this
> %TABLE{valign="top" headeralign="left" columnwidths="170,240"}%
> | *Option* | *Range/Values<br />Default* | *Description* |
> %SEARCH{ "Group != 'Obsolete'" topic="ConfigOption*" casesensitive="on"
> type="query" nosearch="on" nototal="on" order="formfield(Option)"
> excludetopic="ConfigOptionTemplate, ConfigOptionForm" format="|
> [[$topic][$formfield(Option)]]| Values: $formfield(Range)<br />Default:
> $formfield(Default) | $formfield(Description) |"}%
> What is going on?
>
> First line is a Macro %TABLE... which defines how the table looks like.
> Mostly allignment of text and columnwidths
>
> Then | *Option* | *Range/Values<br />Default* | *Description* |
>
> Which is he header of the table. Notice how you can use HTML in the markup.
> And then the smart feature - the formatted SEARCH.
>
> The SEARCH looks up all pages that start with ConfigOption. Note the
> topic="ConfigOption*" where * is a wild card.
>
> And it exclude the topics where Group != 'Obsolete'
>
> What is this? Is it a database? Well almost. I will get back to that.
>
> There are some more options for the SEARCH that controls how it presents
> data. In this case it basically means "shut up with all your noise" and
> finally there is the format parameter which defines how the pages (topics)
> are presented.
>
> Each found topic becomes a table row.
>
> format="| [[$topic][$formfield(Option)]]| Values: $formfield(Range)<br
> />Default: $formfield(Default) | $formfield(Description) |"}%
>
> So the format is a row where
>
> First column is a link to the page that defines the parameter.
>
> Second column is a combination of the field values for Range and Default
> values.
>
> Third column is the description
>
> So each motion.conf option has its own wikipage. The naming convention is
> ConfigOptionOptionName where OptionName is a WikiWord version of the option.
> Simple. It does not have to be but that is how I defined it and it makes it
> easy to find the right page
>
> Now to the config option pages.
>
> Let us take an example. The option "height" from motion conf is defined on
> http://www.lavrsen.dk/foswiki/bin/view/Motion/ConfigOptionHeight. So the
> topic (Pages are called topics in Foswiki - horrible I know) is
> ConfigOptionHeight.
>
> When you look at it you see a plain descriptive text
>
> And below a table which is a Form. The structure of this form is defined in
> ConfigOptionForm which looks like
>
> Form Topic for motion.conf options
>
> Name: Type: Size: Values: Tooltip message:
> Option text 50 Option Name - always lower case and
> with underscore between words
> Type select 1 Boolean, Integer, String, Discrete Strings Date
> type of option
> Range text 70 min: x, max: y Range for integers, or list of allowed
> strings/values
> Default text 50 Default value when option is commented
> out
> Description textarea 80x4 Short Description
> Group select 1 Runtime Options, Capture Device, Round Robin, Motion
> Detection Settings, Image File Output, Movie File Output,
> Snapshots, Text Display, Target Directories and Filenames, Live Webcam
> Server, HTML Based Control, Tracking, External Commands, Common Options For
> Database, Database Options For MySQL, Database Options For PostgreSQL, Video
> Loopback Device, Debugging for Programmers, Thread, Obsolete Option group
> from motion.conf
> So in reality it is like a primitive database where each option is a record
> in a database and the database fields are
>
> Option: The name of the option
> Type: One of the values Boolean, Integer, String, Discrete Strings
> Range: is a plain text field where you define the range of valid values if
> there is a range
> Default: is the default value
> Group: Is one of the values - Runtime Options, Capture Device, Round Robin,
> Motion Detection Settings, Image File Output, Movie File Output, Snapshots,
> Text Display, Target Directories and Filenames, Live Webcam Server, HTML
> Based Control, Tracking, External Commands, Common Options For Database,
> Database Options For MySQL, Database Options For PostgreSQL, Video Loopback
> Device, Debugging for Programmers, Thread, Obsolete
>
> The group is used to be able to autogenerate the documentation and present
> the different options grouped together. If you need a new group you edit the
> ConfigOptionForm topic and the new value will be in the pick list
>
>
> To create a new ConfigOptionXXXXX topic you create it first and then add the
> ConfigOptionForm to the topic and it then gets the nice structured database
> like fields to it. Very simple once you get the idea.
>
> Once you have the the config options defined as one topic for each option
> only fantasy limits the ways you can present the data using the SEARCH macro.
>
> And this is what I do in the Motion Guide. In
> http://www.lavrsen.dk/foswiki/bin/view/Motion/ConfigFileOptions it creates
> the table of all config options.
>
> Back to the Motion Guide. Now that you know what is going on let us look at
> http://www.lavrsen.dk/foswiki/bin/view/Motion/MotionGuideBasicFeatures.
> Again just a bunch of INCLUDEs.
> And inside each included topic I have a plain text introduction. And then
> followed by a SEARCH that presents the the options based on a section
> criteria based on Group value. I can see I need to simplify the SEARCHes a
> little because there is a newer query syntax available now in Foswiki that
> works a bit like SQL. I will update all those.
>
> But the principle is the same all over. The documention is a mix of plaintext
> and reuse of the ConfigOptionXXXX topics.
>
> http://www.lavrsen.dk/foswiki/bin/view/Motion/MotionGuideAlphabeticalOptionReferenceManual
> simply lists ALL the config options in one big document.
>
And now to the man page
> It is a bit hidden. It is under
> http://www.lavrsen.dk/foswiki/bin/view/Motion/MiscellaneousInformation and
> there you find
> http://www.lavrsen.dk/foswiki/bin/view/Motion/MotionOptionsAlphabeticalManpage
>
> And what is under the hood of that?
>
> http://www.lavrsen.dk/foswiki/bin/view/Motion/MotionOptionsAlphabeticalManpage?raw=on
>
> First some plain text Main page intro. Nothing fancy and all within <pre> and
> </pre> tags that makes Foswiki show the text as raw code but still interprets
> macros.
>
> %STARTATTACH...% and %ENDATTACH...% enclose the text we want saved in a man
> page file.
> Each time you edit and save the page a new man page is created and attached
> to the topic. Yes you can also attach files to the wikipages. In this case a
> plugin does it automatically each time you save.
>
> Inside the pre tags you find a SEARCH macro.
>
> %SEARCH{ "Group != 'Obsolete'" type="query" topic="ConfigOption*"
> casesensitive="on" nosearch="on" nototal="on" order="formfield(Option)"
> excludetopic="ConfigOptionTemplate, ConfigOptionForm,
> ConfigOptionFfmpegFilename, ConfigOptionMinimumGap" format=".TP$n().B
> $formfield(Option)
> $percntCALC{\"$LOWER($formfield(Type))\"}$percnt$n()Values: $formfield(Range)
> / Default: $formfield(Default)$n().br$n()$formfield(Description)"}%
>
> It again find all the options and present them neatly in a format that makes
> sense in a man page.
>
> In this case it presents all options except the ones that are in marked as
> Obsolete in the Group field. So now you know how to hide the options that are
> removed in the new versions. Change the group field to Obsolete and it is
> hidden from all views but can be presented on a list of obsolete options.
>
> The Macros in Foswiki are parsed top to down, left to right, inside out.
>
> So when you want to put macros inside the format string of the SEARCH you
> have to hide the macros (inside out) until the search is run. The $percnt or
> $percent is the way you delay the macro expansion inside SEARCH.
>
> So first the SEARCH finds all the option topics, then creates the table rows,
> replaceing all the $percnt with "%" and when the SEARCH is complete the the
> now visible macros get parsed. In this case the CALC macro which is a swiss
> army knife of small functions. Here is changes text to lower case.
>
> I do not expect you guys to understand all this. But you can easily edit the
> pages that are already there.
> With a little help you can create new config option topics and they then
> automatically appear in the Motion guide in the right chapter based on the
> Group field.
> And if you remove an option you change it to the obsolete group.
>
> When you want to generate a new man page - just look up
> http://www.lavrsen.dk/foswiki/bin/view/Motion/MotionOptionsAlphabeticalManpage.
> Edit the page and save it. And then download the updated "motion.1"
> attachment. Easy, right?
>
> You edit one config option file one place. And all the many versions of the
> options tables, the reference manual, the detailed manual, the man pages -
> everything is up to date. THAT is WHY the Motion guide is on Foswiki. It
> takes a little effort to get the head around it but then it is easy to
> maintain
>
> And I will gladly do that. I am using Foswiki at work every day. I just need
> you guys to ping me when you need to update something that is not just a
> simple edit of an existing page
>
>
> The motion guide which is included when you build Motion (at least from the
> old SVN version) simply downloads the HTML from
> http://www.lavrsen.dk/foswiki/bin/view/Motion/MotionGuideOneLargeDocument
>
> And it does it in a mode where all the menus and shit is removed and you just
> get a plain HTML file. You can see some grumpy users that added a note that
> the file is out of date and that people have to read the code to find out how
> it works. That is so wrong and not easy if you do not read C code.
>
> Long email. But the few of you that are interested should not understand how
> it works. I will update the SEARCH syntax used to query search instead of the
> old regex searches used which are a bit dodgy to read.
>
> Kenneth
>
>
>
>
>
>
>
>
>
>
>
>
> ------------------------------------------------------------------------------
> _______________________________________________
> Motion-user mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/motion-user
> http://www.lavrsen.dk/twiki/bin/view/Motion/WebHome
-------------- next part --------------
An HTML attachment was scrubbed...
------------------------------
------------------------------------------------------------------------------
------------------------------
_______________________________________________
Motion-user mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/motion-user
End of Motion-user Digest, Vol 123, Issue 7
*******************************************
