[FOSS-GPS] FoxtrotGPS documentation (format? license?)

[Joshua Judson Rosen]

David <dbannon at internode.on.net> writes:
>
> OK Joshua, sounds like the only problems we have left then are format
> and license, the easy ones (I don't think) !
>
> Seriously, I love my man pages, for command line tools, the only way
> to go. However, people using GUI apps rarely look for a man page, I
> bet most FoxtrotGPS users don't know it exists. And GUI users want
> embedded pictures, nice formatting.

I'm inclined to agree; even among people who /are/ familiar with
man pages, there's a pretty common memory of `the revelation'--
the point at which they were told by someone about the `man' command,
and suddenly everything became so much easier. And, you're right:
there are no pictures--and that can actually be pretty important
when trying to explain something visual like this.

I do want to continue to include some sort of man page just because:

    * distributions like having them;
    * some people /do/ look there first.

If we have real documentation in the form of a PDF or something, though,
then it should be fine to just maintain a `shim' man page--and even
autogenerate with help2man or something.

There's a question here that I'm not sure I have an answer for,
though: how *do* users know where to find the PDF/whatever manual
that's stashed off in /usr/share/doc/...? Where do users *expect*
to find documentation?

Maybe the answer is simply: `in the Help menu!'?

> So what are the alternatives ?
>
> Docbook, LaTeX etc has, IMHO, too high a learning curve for a project
> like this.

Probably--I've never really learned to use either of those
(they always seemed too intimidating...).

> HTML ? Impossible to maintain.

Yeah--`been there, done that, wanna see my scars?' ;)

> MS Word -> [PDF; HTML] Please, please  don't even think that way.

Heh.

> AsciiDoc has some noticeable flaws, don't think if it as a one source
> many formats unless you are willing to compromise the appearance of
> the outputs. On the other hand, its text 'source' is quite easily
> human readable, quite presentable. It makes reasonable HTML very
> easily and the PDF's it makes, with one exception are also good.
>
> Importantly, a decision to go with AsciiDoc is not irreversible, it
> would be easy to convert whats there to just about any other format if
> necessary.

Well, `if I had my druthers'..., I'd be inclined to just go with texinfo
(bear with me for a minute--I'll explain!); but I'd rather have the
documentation get written in a format I'm not entirely comfortable with
than that it not-get-written in a format that I like--and I like
text that you guys have written so far!

I'm generally skeptical of `lightweight markup' languages like asciidoc,
these days--after having been through setext, markdown, wikicreole,
org-mode, and a half-dozen others..., they never seem to end up actually
being as `lightweight' as they seem at first glance--mostly because
there's just too much `DWIM' in them, so I always feel like I'm fighting
to get them stop guessing at `What I Mean' and just let me tell them.
And I see a couple of obvious `nits' like that in the asciidoc code that
you've put together (like: how do we fix the issue where everything
between two "~" characters in different file-paths is being subscripted(?)).

But I'm open to trying it if you guys can help me figure out how to
integrate it into the build-system, so that we can just have `make dist'
generate docs--and figure out what people actually need to install
in order to work with it?

Someone actually suggested AsciiDoc to me a while back, if only as a
more readable/maintainable source for the manpage. I spent some time
trying to figure that out but then basically gave up on it until you and
Til re-suggested it; I see now that the `how to write a man page in
asciidoc' doc was just squirrelled away somewhere other than where I was
expecting it to be.... And `writing a man page in asciidoc' does look
like it's mutually exclusive with writing any other kind of document in
asciidoc....

Now, about those `druthers' that I said I'd explain...:

I know "texinfo" has both "tex" and "info" in its name, but that doesn't
actually mean either `intimidating source-format like latex' or
`documents you have to read in a terminal with the `info' command'.
texinfo source is actually mostly just plaintext, with a
little (easy-to-understand--I think...) markup where necessary,
and converts to all of the outputs that we want.

I went and learned enough texinfo to transcribe what we have now
(including the additions from you and Til), and put together some
example source and output-files (like you've done with asciidoc);
having done that, here's what I see texinfo has going for it:

    * It produces pretty nice HTML output (with images!), e.g.:
      <http://whipit.gd/foxtrotgps.html>

      (many of the web-page that you end up reading `instead of
       the info page' may actually be texinfo manuals)

    * It produces pretty nice PDF output (with images, hyperlinks,
      TOC, etc.), e.g.: <http://whipit.gd/foxtrotgps.pdf>

    * It produces pretty nice plaintext output (`with images',
      believe it or not--if you can come up with an ASCII-art
      alternative to an image, `makeinfo --plaintext' will
      figure out that it should put that into the text rendition
      of the document...); e.g.: <http://whipit.gd/foxtrotgps.txt>

    * It's straightforward and *easy* to integrate it into
      the build-system--generation of HTML, PDFs, PostScript,
      and some other formats basically `just works' thanks to
      logic that's already in Automake (cf. the bzr branch
      on Launchpad, below).

    * It doesn't seem to have the `too much DWIM' problem.

And, yes, it (also) produces info pages..., which actually seem to be
be more useful/versatile than expected: for one, it's not just the `info
command' that knows how to read them--GNOME's `yelp' help-viewer tool
can actually display them, for example; *with inline images*.
And I believe KDE and other desktop environments have similar tools
(like `kdehelp'?).

My `docs in texinfo with PDF/HTML/etc output' experiment is in
this bzr branch in Launchpad, for review:

     https://code.launchpad.net/~rozzin/foxtrotgps/texinfo

But, like I said--if you guys find asciidoc more workable, and you can
help me figure out how to integrate it into the build-system, I'll
go with it.

> So, I suggest that the FoxtrotGPS web page has HTML, the distribution
> has the text source file, and, perhaps a PDF. A man page then needs to
> say little more that see the other docs and maybe mention the much
> lauded command line options and the two extra utilities.

Exactly :)

> License ?  I'd go along with what ever the developers decide but my
> preference would be CC or, maybe just because its easy, GPL. Clearly,
> I want no ownership.

Doing a quick survey of relevant communities where our documentation
might end up being used (and I'd like to make that easy/kosher for
them), and/or which are likely to influence others:

    * Wikipedia uses a dual-license of CC BY-SA 3.0 +
     (no specific version of) GNU FDL

    * The OSGeo wiki uses CC BY-SA 2.5.

    * The OpenStreetMap wiki uses CC BY-SA 2.0.

    * The Openmoko wiki uses GNU FDL 1.2 (but it's not actually a `live'
      project right now--hopefully it'll come back...)

    * The Qi Hardware wiki uses a dual-license of CC BY-SA
      (unspecified version) + GNU FDL (unspecified version).

    * There was a big row in Debian, a while back, about whether GNU FDL
      was DFSG-compatible, and I believe they settled on something like
      `FDL with no invariant sections is OK; but FDL with invariant
      sections needs to be stripped from source tarballs, packaged
      separately, put into the `non-free' section and not installed by
      default'.

      Looking at <http://wiki.debian.org/DFSGLicenses>, it looks like
      Debian accepts CC BY-SA 3.0 but rejects earlier versions--
      *somewhat* similarly to how they reject FDL-with-invariant-sections.

      (and Ubuntu just uses the package basically as-is from Debian,
       since we're off in their `universe' section.)

      I have no idea what Fedora's / Red Hat's policies are
      (Til may, since I believe he's responsible for the
       foxtrotgps package in Fedora).


If I'm reading them correctly, CC BY-SA 2.0, 2.5, and 3.0 all have
`this or any later version' clauses built-in, so us using 3.0
to avoid the various issues of previous (now deprecated) versions
of the license doesn't /necessarily/ interfere with communities
like OSGeo and OSM making use of it if they really want to....

So... I guess `CC-BY-SA 3.0 + GNU FDL (w/ no invariants)' sounds
like a winner?

-- 
"Don't be afraid to ask (λf.((λx.xx) (λr.f(rr))))."


> http://www.users.on.net/~dbannon/FoxDoc/foxtrotgps.html
>
> David
>
> Joshua Judson Rosen <rozzin at geekspace.com> wrote:
>
> >Charles Curley <charlescurley at charlescurley.com> writes:
> >>
> >> On Sat, 10 Nov 2012 12:21:22 +1100
> >> David Bannon <dbannon at internode.on.net> wrote:
> >>
> >> > http://www.users.on.net/~dbannon/FoxDoc/foxtrotgps.html
> >>
> >> I think it's useful. I had no idea the keyboard shortcuts were there!
> >> There's a lot of work to complete it, but this is an excellent start.
> >
> >The listing of keyboard shortcuts is from the manpage update last week;
> >I think the question isn't really about whether to document things,
> >or even about what to document, but really of what `source format'
> >should be used for documentation.
> >
> >Right now our source-format for documention is troff (with `mandoc'
> >macros). It's great for formatting, which makes it great for printing
> >and OK for reading with a `man page' reader (e.g.: man, info, tkman, yelp)
> >but it has a little bit of a learning curve and is (I find) somewhat hard
> >to read. Apparently other people also find it hard to read ;)
> >
> >Also, I guess there also is (or should be) a question of what license to use
> >for the documentation--because it should be easy for people to `repurpose'
> >it into useful formats that may not have been thought of yet. Right now,
> >there's no license declared specifically for the documentation;
> >if we leave it like that, then we're probaby implying that it's
> >GPL'd along with the rest of the codebase, and then technically people
> >are supposed to distributed annotated source whenever they publish it...,
> >which might put people off from, say, making `FoxtrotGPS quick-reference',
> >mugs or T-shirts (it could happen!).
> >
> >Daniel Baumann wrote the initial version of the man page and generously
> >offered to basically let us distribute it under whatever license terms
> >we wanted, and all of the other content added so far to that man page
> >(which, granted, isn't that much!) has been written by me, so it's
> >not too late to actually *pick a license for the documentation*.
> >
> >I don't know what the popular free license for documentation is,
> >these days--seems like GFDL never really cought on; Creative Commons
> >BY-SA (Attribution Share-Alike), maybe? Or 3-clause BSD?