FVWM: mvwm - documentation

Post by Michael Treibton
Hi,
taking a look at the mvwm repository, i notice that the documentation
is using xml. is this still the case? it looks like some of the
documentation hasn't changed given some changes to the functionality
in mvwm???

Have a read of this thread:

http://thread.gmane.org/gmane.comp.window-managers.fvwm.devel/5886

-- Thomas Adam

--
"Deep in my heart I wish I was wrong. But deep in my heart I know I am
not." -- Morrissey ("Girl Least Likely To" -- off of Viva Hate.)

Michael Treibton

2014-08-23 20:36:38 UTC

http://thread.gmane.org/gmane.comp.window-managers.fvwm.devel/5886

so i have to learn this 'roff' is it? why not use asciidoc which means
you can use plain language - theres a lot of syntax markup with
mdoc/groff - that makes writing documentation harder.

That seems wasteful to me

Michael

Thomas Adam

2014-08-23 22:40:17 UTC

http://thread.gmane.org/gmane.comp.window-managers.fvwm.devel/5886

so i have to learn this 'roff' is it? why not use asciidoc which means
you can use plain language - theres a lot of syntax markup with
mdoc/groff - that makes writing documentation harder.

So, I think the point here is to fundamentally appreciate the difference
between the roff family (groff, nroff, and troff) and what mdoc
provides.

Back in the '60s, roff (RUNOFF) came about as a means of a
typesetter---a way of formatting text. Fast forward some forty years
and the essence of that survives, in terms of the GNU implementation of
roff (groff). nroff (new-roff) and troff (AT&T-derived formatting;
includes things like eqn, tbl, etc.) are all variants/extensions of the
same thing. In fact, in terms of troff, TeX actually stole some of
those techniques (c.f. eqn for instance).

What mdoc provides is a sort of subset of roff---it's designed from the
ground-up, and focuses on the ability to write man pages in it
(BSD-licenced; OpenBSD has been using it for the last four years). It's
not as feature-rich as roff, and I've heard some dyed-in-the-wool types
moan that for GNU/Linux this has some impact in terms of what's rendered
in man pages, etc., although I personally consider that a red-herring.
I've yet to come across a man page where there's a reliance on some
troff extensions, for example.

So with mdoc you have at your disposal a well-engineered back-end system
which can be used to create just man pages, with the added bonus of
rendering out other types as well (including (X)HTML/stylesheets). I
was only on the periphery of the work done by Scott Smedley when Docbook
was introduced, but even since that point, the way in which
documentation culminates is horrendous. It's horrific and I for one
never want to work with it again. I know I'm not alone in thinking
that; and that's not to imply the work done by those to introduce
docbook was ever in vain; far from it. It's just something where there
was not enough discussion and the benefits didn't outweigh the
replacement, unfortunately.

Of course since that point, there's been an explosion of
markup/markdown/hidden-markup type things where you can try and write
all these things in plainer-looking English and hope the parser can
render it down appropriately. That's what Asciidoc claims to do, and a
few years ago, I started to define a switch to it, to try and alleviate
a need to know shitty XML. As it happens, although that kind of worked,
Asciidoc itself is not stable, in my opinion, and you're left at the
mercy of things changing too frequently, not to mention a sizeable
build dependency.

So when you come down to it, the benefits to not writing in *roff are:

* Can be abstracted away; the syntax is irrelevant;
* Lower learning-curve as the text can be written more in "plain
English"

But the downsides are:

* Inflexibility with the abstraction not providing the lower-level
macros for text-formatting;
* Larger dependencies to compile a document;
* Sometimes an overhead to learning the abstracted syntax

When you put this on-balance, along with the documentation's history to
date, going back to the wire, and enforcing mdoc (roff) as a markup
language brings more benefits to my eyes, than anything else. It's
verbose, sure, but for a reason. It is what it is, and requires no
additional packages, etc. It's the lowest common denominator.

Post by Michael Treibton
That seems wasteful to me

See above. Anything else I can do for you, let me know.

-- Thomas Adam

--
"Deep in my heart I wish I was wrong. But deep in my heart I know I am
not." -- Morrissey ("Girl Least Likely To" -- off of Viva Hate.)

Glenn Golden

2014-08-23 23:09:21 UTC

http://thread.gmane.org/gmane.comp.window-managers.fvwm.devel/5886

so i have to learn this 'roff' is it? why not use asciidoc which means
you can use plain language - theres a lot of syntax markup with
mdoc/groff - that makes writing documentation harder.

So, I think the point here is to fundamentally appreciate the difference
between the roff family (groff, nroff, and troff) and what mdoc
provides.
Back in the '60s, roff (RUNOFF) came about as a means of a
typesetter---a way of formatting text. Fast forward some forty years
and the essence of that survives, in terms of the GNU implementation of
roff (groff). nroff (new-roff) and troff (AT&T-derived formatting;
includes things like eqn, tbl, etc.) are all variants/extensions of the
same thing. In fact, in terms of troff, TeX actually stole some of
those techniques (c.f. eqn for instance).
What mdoc provides is a sort of subset of roff---it's designed from the
ground-up, and focuses on the ability to write man pages in it
(BSD-licenced; OpenBSD has been using it for the last four years). It's
not as feature-rich as roff, and I've heard some dyed-in-the-wool types
moan that for GNU/Linux this has some impact in terms of what's rendered
in man pages, etc., although I personally consider that a red-herring.
I've yet to come across a man page where there's a reliance on some
troff extensions, for example.
So with mdoc you have at your disposal a well-engineered back-end system
which can be used to create just man pages, with the added bonus of
rendering out other types as well (including (X)HTML/stylesheets). I
was only on the periphery of the work done by Scott Smedley when Docbook
was introduced, but even since that point, the way in which
documentation culminates is horrendous. It's horrific and I for one
never want to work with it again. I know I'm not alone in thinking
that; and that's not to imply the work done by those to introduce
docbook was ever in vain; far from it. It's just something where there
was not enough discussion and the benefits didn't outweigh the
replacement, unfortunately.
Of course since that point, there's been an explosion of
markup/markdown/hidden-markup type things where you can try and write
all these things in plainer-looking English and hope the parser can
render it down appropriately. That's what Asciidoc claims to do, and a
few years ago, I started to define a switch to it, to try and alleviate
a need to know shitty XML. As it happens, although that kind of worked,
Asciidoc itself is not stable, in my opinion, and you're left at the
mercy of things changing too frequently, not to mention a sizeable
build dependency.
* Can be abstracted away; the syntax is irrelevant;
* Lower learning-curve as the text can be written more in "plain
English"
* Inflexibility with the abstraction not providing the lower-level
macros for text-formatting;
* Larger dependencies to compile a document;
* Sometimes an overhead to learning the abstracted syntax
When you put this on-balance, along with the documentation's history to
date, going back to the wire, and enforcing mdoc (roff) as a markup
language brings more benefits to my eyes, than anything else. It's
verbose, sure, but for a reason. It is what it is, and requires no
additional packages, etc. It's the lowest common denominator.

Post by Michael Treibton
That seems wasteful to me

See above. Anything else I can do for you, let me know.
-- Thomas Adam

Fwiw: As a guy who started at Bell Labs in 1979 (now retired) and wrote gawd
knows how many hundreds of documents in troff [-mm, -man, -metc etc] I heartily
agree with every point Thomas has made. Imo, his brief overview above should
be required reading for anyone contemplating a large doc project.

The learning curve, though somewhat (but not terribly) steeper than the various
more modern "plain English" markups, is well worth the trouble. Even today,
when I write the occasional paper (-mm) or man page (-man), it's invariably in
troff. Ancient perhaps, but even today, nothing beats it, IMO. (The TeX/latex
family seems to be the only serious competitor, and colleagues over the years
familiar with with both seem to like them about equally.)

I would offer the following encouragement to Michael: Every person (without
exception that I recall) who over the years I've badgered, browbeaten,
encouraged, or required to use *roff has been very happy that they took the
plunge. You may laugh that it's 40+ years old, but so are cat, ls, od, sort,
uniq, ........

OK, I'll stop rambling now, with a relevant (and only half-joking) quote
attributed to Henry Spencer:

"Those who do not understand Unix are condemned to reinvent it, poorly."

HTH.

Regards,

Glenn

Michael Treibton

2014-08-23 23:41:19 UTC

Post by Glenn Golden
I would offer the following encouragement to Michael: Every person (without
exception that I recall) who over the years I've badgered, browbeaten,
encouraged, or required to use *roff has been very happy that they took the
plunge. You may laugh that it's 40+ years old, but so are cat, ls, od, sort,
uniq, ........

ok - but i don't see any other alternatives being offered here. if
asciidoc is that bad, how comes other projects including Git use it
and have well structured man pages? they do ok out of using asciidoc,
so why wouldnt mvwm?

If you don't watch this decision it will look like the same thing as
docbook did - that it is here for no reason.

Michael

Glenn Golden

2014-08-24 00:46:39 UTC

I'll leave critique of alternatives to those more familiar with them.

Regarding your observation that asciidoc is capable of generating decent man
pages and other documents, I would offer the analogy that programs like
WordStar, FrameMaker, WordPerfect, DisplayWriter, ElectricPencil, Interleaf,
[insert dozens more here]... were also capable of rendering decent-looking
documents. But how many source documents written in those languages would it
even be possible to render today at all, in any form whatsoever?

To be fair, asciidoc (due to its simplicity) may not die as quickly and
thoroughly as did all the above. But still, I would opine that 40 years
from now, it will have been supplanted. Otoh, I suspect that professional-
grade low-level tools like troff and TeX (upon which are built numerous macro
packages for ease of use, mdoc being one of them) will survive indefinitely,
just as they have survived (and even flourished, among documentation
professionals) for the past 40 years, and for the same reasons: The underlying
substrate is very high quality, and they perform a single function very well.
The Unix philosophy. The same reason cat, ls, sort, .... are still around.

Post by Michael Treibton
If you don't watch this decision it will look like the same thing as
docbook did - that it is here for no reason.

You may be right, Michael. But imo, the opposite is more likely: Documents
written for heavily worked over low-level tools like troff and using well-
known macro packages (like -man, -mm, -mdoc, etc.) are more likely to survive
the test of time.

Anecdotally: A few years ago I was asked to reproduce a paper I'd written in
the early 90's. It was in troff, using Bell Labs' "Memorandum Macros" package.
With about 15 minutes googling for a modern equivalent of that package, and
perhaps another hour or so of dorfing around with small style details, I was
able to re-render the paper in camera-ready PDF form at 1200 dpi (including
numerous images). I would not be surprised to be able to do pretty much the
same thing 20 years from now, other than personal impediments like senility
or being dead, which are problems of another sort. But I bet troff will
outlive me.

Just my 2c. But to this point, I think history backs up that view.

Anyway, to end on an encouraging note: "Try it, you'll like it".

Regards,

Glenn

Dan Espen

2014-08-24 01:57:47 UTC

Post by Glenn Golden
Regarding your observation that asciidoc is capable of generating decent man
pages and other documents, I would offer the analogy that programs like
WordStar, FrameMaker, WordPerfect, DisplayWriter, ElectricPencil, Interleaf,
[insert dozens more here]... were also capable of rendering decent-looking
documents. But how many source documents written in those languages would it
even be possible to render today at all, in any form whatsoever?
To be fair, asciidoc (due to its simplicity) may not die as quickly and
thoroughly as did all the above. But still, I would opine that 40 years
from now, it will have been supplanted.

I sure hope that in the future we will not be writing documentation
meant to look like paper.

My guess for the future of documentation is HTML.

--
Dan Espen

Thomas Adam

2014-08-24 09:00:46 UTC

Post by Michael Treibton
If you don't watch this decision it will look like the same thing as
docbook did - that it is here for no reason.

The requirements for what we want are still the same thing as what
Docbook brought us:

* The ability to render man pages;
* The ability to have the documentation in multiple files;
* The ability to render in different formats

I know Asciidoc can do this. I know that markdown can do this. I know
you can come back and tell me any number of the plethora of
typesetting/abstraction programs can do these things.

That's nice.

But heed my previous email; when you get down to it, *roff (mdoc) *is*
the abstraction layer. That mdoc allows for all these things, and is
still letting you use the very typesetting language man pages render
with, etc., is a winner in my eyes.

So far all you've done is peddle rhetoric. I take your point on board
about due consideration, and I like to think I've done that and
justified it. If anyone else can prove that we've got this wrong, or
that fundamentally, what mdoc provides cannot address a certain part of
the documentation, then I really do want to hear about that.

But I am not going to sit here and justify ever single point in as much
detail as I have done thus far; it's distracting me from my ABNF
work---you *do* want a documented parser at some point, right?

Now, if you'll excuse me...

-- Thomas Adam

--
"Deep in my heart I wish I was wrong. But deep in my heart I know I am
not." -- Morrissey ("Girl Least Likely To" -- off of Viva Hate.)

Michael Treibton

2014-08-24 15:09:13 UTC

Post by Thomas Adam
But heed my previous email; when you get down to it, *roff (mdoc) *is*
the abstraction layer. That mdoc allows for all these things, and is
still letting you use the very typesetting language man pages render
with, etc., is a winner in my eyes.

i looked at the work done here -

https://github.com/ThomasAdam/fvwm/tree/ta/asciidoc

which i think is the prior work by you to make the man pages render in
asciidoc. Look at this example:

https://github.com/ThomasAdam/fvwm/blob/ta/asciidoc/Documentation/FvwmDecor/DefaultColors.txt

the mdoc version is going to be a lot more work - many more commands
to include - and it gets in the way. i don't even need to provide the
mdoc example.

Also see -

http://comments.gmane.org/gmane.comp.window-managers.fvwm.devel/4972

your original announcement to use asciidoc - and even tho i've read
everything you've put, this is back-peddling. i would rather continue
to use asciidoc if i were ever going to help with the documentation.

again, why can't we use it? extending your original work should be easier, no?

Michael

Dominik Vogt

2014-08-24 22:10:24 UTC

https://github.com/ThomasAdam/fvwm/blob/ta/asciidoc/Documentation/FvwmDecor/DefaultColors.txt
the mdoc version is going to be a lot more work - many more commands
to include - and it gets in the way.

That example lacks almost all the markup in the text. It does not
allow to automatically generate links in html format, or identify
command names, command options, styles, strings, key sequences
etc. by markup. An Asciidoc source file without all that is
useless.

I've spent weeks to add the proper markup to the original fvwm man
pages before they were converted to xml. I won't accept any
documentation format that throws all this extra information away
for no reason.

Ciao

Dominik ^_^ ^_^

--
Dominik Vogt

Michael Treibton

2014-08-25 01:02:19 UTC

Post by Dominik Vogt
That example lacks almost all the markup in the text. It does not
allow to automatically generate links in html format, or identify
command names, command options, styles, strings, key sequences
etc. by markup. An Asciidoc source file without all that is
useless.

But asciidoc *can* do that; it's just the example is minimal.

Post by Dominik Vogt
I've spent weeks to add the proper markup to the original fvwm man
pages before they were converted to xml. I won't accept any
documentation format that throws all this extra information away
for no reason.

it doesn't throw it, it abstracts it.

are you saying you agree with mdoc as a good solution to this then?

Michael

Thomas Adam

2014-08-25 08:43:00 UTC

Post by Michael Treibton
it doesn't throw it, it abstracts it.

And therein lies the problem, because as I look back over the initial
asciidoc work that I did, I note myself:

Asciidoc's man page driver enforces the three sections of NAME,
SYNOPSIS, and DESCRIPTION, which makes writing generic top-level
descriptions for sections a pain, but see what I've done for the
SYNOPSIS section by simply using "fvwm *" -- I think that'll be
sufficient.

The abstraction point isn't of any use to me---I can't easily control
certain things which are essential to man pages---at least, not
trivially. If I could, say via macros, that almost defeats the point of
this abstraction. As soon as you go away from the abstraction, you've
lost all usefulness of it.

Dominik notes that you lose flexibility this way, and he's spot on.
That's precisely why I don't like these helpful abstractions. Note that
where asciidoc shines for me is having a common format to produce *many*
different outputs; assuming you can live with those outputs being quite
minimal.

Post by Michael Treibton
are you saying you agree with mdoc as a good solution to this then?

I'm sticking with it, absolutely! Michael, you don't need to sit there
and show us that asciidoc can do things; we know this. At this point,
you can either try and poke around with mdoc, or not. But I cannot
waste anymore time on this discussion; what is quickly turning into a
polemic.

I get that you don't agree with this decision, but given we've seen
nothing from you other than these sets of emails, I'm starting to wonder
what your point is---either contact Roman to get an understanding of
what he's doing with the documentation, or don't. Either way, that's
how you can best start to help from now on.

This conversation is over.

-- Thomas Adam

--
"Deep in my heart I wish I was wrong. But deep in my heart I know I am
not." -- Morrissey ("Girl Least Likely To" -- off of Viva Hate.)

Michael Treibton

2014-08-25 11:20:14 UTC

Post by Thomas Adam
This conversation is over.

i am biterly concerned and disappointed by this decision - i do not
understand how you can be closed minded and not take the usefulness of
asciidoc.

i thought mvwm was going to be a nice project with a different
attitude to things - but i can see now this is wrong. please dont harm
this project - because if this decision about the doc is an indicator,
i think you should leave now.

Michael

Thomas Adam

2014-08-25 12:29:26 UTC

Post by Thomas Adam
This conversation is over.

i am biterly concerned and disappointed by this decision - i do not
understand how you can be closed minded and not take the usefulness of
asciidoc.

Michael, it's been pointed out to me that my comment was a little
harsh--and I had indeed intended to be, other than a firmer "I've
nothing more I can say that I've not done already". Unlike the
patronising hyperbole I received off-list, I won't patronise you in the
same way, other than to note that I can't add anything more to the
conversation than what I have already.

mdoc seems like the logical choice at the moment, and until such time
that it doesn't provide what we need (assume some further change in
requirements, for example), then we'll look at alternatives. But for
now, I'm very keen to try this and see how it pans out.

-- Thomas Adam

--
"Deep in my heart I wish I was wrong. But deep in my heart I know I am
not." -- Morrissey ("Girl Least Likely To" -- off of Viva Hate.)

Michael Treibton

2014-08-25 13:48:41 UTC

Post by Thomas Adam
Michael, it's been pointed out to me that my comment was a little
harsh--and I had indeed intended to be, other than a firmer "I've
nothing more I can say that I've not done already". Unlike the
patronising hyperbole I received off-list, I won't patronise you in the
same way, other than to note that I can't add anything more to the
conversation than what I have already.

I have looked at mdoc and it seems verbose - more than asciidoc. but i
can see also its usefulness. i was always under the spell of asciidoc
- that it provided a good enough layer to not worry about the details.

now though ive taken a look at it - i will try and use it - and really
give it a chance.

also let me apologise to you - i did not wish to sound harsh. i had
always believed in asciidoc but can maybe see now where it doesn't
always fit for man page writing. for example, .SH options render
differently compared to the way asciidoc indents items - i haven't
compared the asciidoc output yet to see why its different.

so i - how do you say - eat my own hat?

i received an email from Glenn Golden who seems to know lots about
mdoc - maybe he can help? although he seems to dislike you intently!!
sorry to say that!

Michael

Glenn Golden

2014-08-25 15:43:29 UTC

Post by Michael Treibton
i received an email from Glenn Golden who seems to know lots about
mdoc - maybe he can help?

I'll be glad to if I can. mdoc(7) is probably a decent place to start,
if somewhat terse like most man pages. I did some fairly detailed rework
on a few existing man pages a few years back, and was able to learn enough
just from mdoc(7) to get the job done. (But to be fair, I also was familiar
with the 'mm' and 'an' macro packages already, so perhaps mdoc.7 is not
really the best place to start for a newcomer.)

There's a tutorial man page too, mdoc.samples(7), which looks pretty decent,
though I've not read it in detail. But certainly, working from an existing
man page as a basic template is probably the best way to start. I'd suggest
choosing a fairly complex one, so you can see how to some of the more
detailed formatting and style stuff is accomplished.

Another tip is to use gs(1) with the "monitor file state" option enabled to
provide near-instantaneous re-rendering in realtime. So as you make changes
in the file, you can see the result immediately as soon as you groff(1) it
(which you can of course invoke from within any ATE.) Pseudo-WYSIWYG! :)

Post by Michael Treibton
although he seems to dislike you intently!!

Wow, all I can say is: Oyoyoy... no good deed goes unpunished!

The obvious intent of my note to you was to un-discourage you from taking
Thomas' dogmatic "this conversation is over" too seriously and decide not to
help with the doc.

I really winced that you chose to (mis)characterize my feelings toward him
in public here on the list, since my note to you was obviously private.
In any case, it's certainly not true that I dislike Thomas, intensely or
otherwise, only that he's a bit of a conundrum, a force for Good and Evil
on the list: Technically excellent and always helpful, but occasionally also
disruptive due to his language habits. (And in view of your angry initial
reply to him, telling him that he ought to "leave the list", it certainly
seemed as though you were offended, hence it seemed a worthwhile effort on
my part to try to calm the situation a bit.)

Btw, you forgot to mention that I also said of Thomas:

"...he's a highly skilled developer, and has been nothing short of
extraordinarily helpful to people coming here with questions and problems.
He's also written a good deal of the code and doc. On a technical level,
I find myself in agreement with most of his views, not only about fvwm
per se, but about coding and doc in general. IMO, he is a top-notch
programmer and has his technical head on straight."

And after offering a critical opinion of his occasionally curt manner on
the list, also added

"On the other hand, I do think that behind the gruff and sometimes
offensive exterior, he's truly a nice and decent fellow."

How you got from the above to "intensely disliking" him, I don't know, but
just for the record, it's absolutely not true. Thomas is who he is, and if
you don't like his manner -- and honestly, I don't sometimes -- then you
can either interact with the list read-only, as I mostly have, or just get
used to it. He's who he is, and isn't going to change.

Hth,

Regards,

Glenn

Dominik Vogt

2014-08-25 18:33:55 UTC

Folks, I'm back from my (very) extended fvwm holiday for roughly a
month now, and I hardly know this place anymore. Can we *please*
keep the personal discussions off, and the technical discussions
on the list?

Really, developers can be difficult at times (myself being a good
example), but certainly if we try, everybody can get along with
each other regarding the technical stuff. Working on fvwm and the
rewrite is tedious and - as stated elswhere - can be boring and
may not be rewarding immediately.

All the more, help from people who are willing to tackle boring
stuff is welcome. There are no intentions to change development
to a closed model, and I'm eager to hear any opinions and comments
by any user or developer on the direction we're taking - as long
as they eventually reach the necessary techical level.

But still, please try to respect the many hours of work some of us
have spent for fvwm (and the experience we gained), and please
understand that everybody needs to spend their time economically.

So, specifically, I ask everybody to really read and think about
the messages on the lists, to assume a constructive attitude, to
accept that people are different and one might find it difficult
to get along with somebody else, who is technically brilliant.
And please try not to launch personal attacks and try not to take
replies personal even if they are.

As it looks like the problems have been sorted out now, can we
please go back to the issues we have to solve? To me it looks
like a good idea to move this thread of discussion from the user's
list to the fvwm-workers list.

Ciao

Dominik ^_^ ^_^

--
Dominik Vogt

Michael Treibton

2014-08-25 21:10:11 UTC

Post by Dominik Vogt
So, specifically, I ask everybody to really read and think about
the messages on the lists, to assume a constructive attitude, to
accept that people are different and one might find it difficult
to get along with somebody else, who is technically brilliant.
And please try not to launch personal attacks and try not to take
replies personal even if they are.

i feel like i should offer a public apology. i did not intend to stir
up so many opinions - and i was clearly not informed of past problems
thomas has caused here - and i did not mean to stir that up.

i can't say i've conducted myself very well - but was dismayed to
receive off-list email from a member of this list detailing his past
encounter with thomas as though it was something i needed to care
about in order to survive here. i find /that/ sort of behavior
unacceptable and off-putting to talk about a lead developer behind his
back in isolation.

i understand decisions are decisions - so i am going to look into this
mdoc language and apply it to this situation and i hope my efforts
will be appreciated.

i want to apologize and offer my apologies to all concerned once
again, and i hope we can move forward from this.

Dominik, i don't want to be the cause for you to not recognise this
place anymore!

Michael

Dominik Vogt

2014-08-25 22:00:00 UTC

i feel like i should offer a public apology.

Apology accepted, but really, there's no need for one. Let's just
forget about past problems on the mailing lists and go back to
work. Everybody will be fine if there is progress in the work.

Post by Michael Treibton
and i hope we can move forward from this.

That is exactly what we need now, especially since the current
work we all do is not very exciting. :-)

Ciao

Dominik ^_^ ^_^

--
Dominik Vogt

Roman Grazhdan

2014-08-25 17:22:59 UTC

So Dominik, you would set requirements later so that I could check what
I'm
doing against them? I like the current manual very much, it's really
helpful and as close to easy to use as a documentation for something
like
fvwm can get, and I'd like it to stay this way.

Dominik Vogt

2014-08-25 18:47:53 UTC

Post by Roman Grazhdan

So Dominik, you would set requirements later so that I could check
what I'm doing against them?
I like the current manual very much, it's really helpful and as
close to easy to use as a documentation for something like fvwm
can get, and I'd like it to stay this way.

Me too. My only personal requirements are that (a) the final,
rendered man page should mostly look like it looks now (not losing
the markup I mentioned, although we have a bit too much at the
moment), and (b) that I'll be able document new features in the
future without much overhead. I've always been very happy with
the roff format we had before the switch to xml.

Before xml there were these short instructions about editing the
man pages right at the top (e.g. in the 2.4.0 tarball):

--
.\" Formating instructions for the fvwm man page:
.\"
.\" - Do not use \f... formatting instructions.
.\" - Avoid single and double quotes wherever possible.
.\"
.\" For further details, please refer to the Linux Man-Page how-to.
.\"
.\" context typeface example
.\" ---------------------------------- -------------- -----------------
.\" filenames: italics (.I) .I .fvwm2rc
.\" command line options of fvwm2 cmd: bold (.B) .B \-cmd
.\" arguments of command line options: italics (.I) .BI \-cmd command
.\" built in commands: bold (.B) .B Move
.\" references to built in commands: bold (.B) .RB See Move
.\" references to man page sections: bold (.B) .RB See SYNOPSIS
.\" references to style options: italics (.I) .RI See Lenience
.\" built in command options: italics (.I) .BI "Move " "0 0"
.\" command syntax: bold/ita. (.BI) .BI "Move [" "x y" "]"
.\" environment variables: italics (.I) .I $DISPLAY
.\" key names: small (.SM) .SM Tab
.\" style names and strings: double quotes "stylename", "x"
.\" single characters: single quotes '@'
.\" module names: bold (.B) .B FvwmTheme
.\" links to web pages: bold (.B) .B http://fvwm.org
.\" acronyms: small (.SM) .SM ICCCM
.\"
.\"
.\" The name fvwm is written in lower case throughout this man page.
.\"
.\" Note that the word "will" is rarely correct in a man page or any document.
.\" Describe what fvwm does, not what it will do, even if you haven't
.\" written the feature yet. dje 2/3/01.
.\"
.\" A note to everyone who needs to write dates. Don't use 2/3/01 notation,
.\" a non-american person simply can't parse such sequence of digits.
.\" Please use 3-Feb-2001 or 2001-02-03 forms. migo 16/May/2001.

Roman Grazhdan

2014-08-25 19:29:06 UTC

On 25.08.2014 22:47, Dominik Vogt wrote:

Wow, this goes right to README! :)

I wish I had it from the start, but it's nice to have it anyway.

Thanks.

Post by Dominik Vogt
.\"
.\" - Do not use \f... formatting instructions.
.\" - Avoid single and double quotes wherever possible.
.\"
.\" For further details, please refer to the Linux Man-Page how-to.
.\"
.\" context typeface example
.\" ---------------------------------- --------------
-----------------
.\" filenames: italics (.I) .I .fvwm2rc
.\" command line options of fvwm2 cmd: bold (.B) .B \-cmd
.\" arguments of command line options: italics (.I) .BI \-cmd command
.\" built in commands: bold (.B) .B Move
.\" references to built in commands: bold (.B) .RB See Move
.\" references to man page sections: bold (.B) .RB See SYNOPSIS
.\" references to style options: italics (.I) .RI See Lenience
.\" built in command options: italics (.I) .BI "Move " "0 0"
.\" command syntax: bold/ita. (.BI) .BI "Move [" "x y" "]"
.\" environment variables: italics (.I) .I $DISPLAY
.\" key names: small (.SM) .SM Tab
.\" style names and strings: double quotes "stylename", "x"
.\" module names: bold (.B) .B FvwmTheme
.\" links to web pages: bold (.B) .B
http://fvwm.org
.\" acronyms: small (.SM) .SM ICCCM
.\"
.\"
.\" The name fvwm is written in lower case throughout this man page.
.\"
.\" Note that the word "will" is rarely correct in a man page or any document.
.\" Describe what fvwm does, not what it will do, even if you haven't
.\" written the feature yet. dje 2/3/01.
.\"
.\" A note to everyone who needs to write dates. Don't use 2/3/01 notation,
.\" a non-american person simply can't parse such sequence of digits.
.\" Please use 3-Feb-2001 or 2001-02-03 forms. migo 16/May/2001.
--

Thomas Adam

2014-08-26 12:36:36 UTC

Post by Roman Grazhdan
Wow, this goes right to README! :)
I wish I had it from the start, but it's nice to have it anyway.

It's fine. Just be aware that not all of markup will be the same with
mdoc---most notably .I, .B, etc., where .Em and .Sy are preferred, etc.
It's worth having a quick check of the typeface and examples before plonking
this in as something for people to adhere to.

-- Thomas Adam

Dan Espen

2014-08-25 20:19:37 UTC

Post by Dominik Vogt

Post by Roman Grazhdan

So Dominik, you would set requirements later so that I could check
what I'm doing against them?
I like the current manual very much, it's really helpful and as
close to easy to use as a documentation for something like fvwm
can get, and I'd like it to stay this way.

Very sorry you still don't like the XML format.
I find it clumsy, but I'm willing to put up with it.
Personally I almost always go online and read Fvwm man pages
as HTML. Anything we can come up with that renders HTML
is good with me.

I want to mention, when I wrote F_CMD_ARGS,
one of the things I had in mind was to put function
documentation in the .c files. I envisioned some kind of
extract run generating the actual man page input.
I was trying to make the functions easy to find by giving
them a uniform appearance.

I thought that would help a lot keeping the source code and
the documentation in sync.

--
Dan Espen

Thomas Adam

2014-08-25 20:27:17 UTC

Post by Dan Espen
Very sorry you still don't like the XML format.
I find it clumsy, but I'm willing to put up with it.
Personally I almost always go online and read Fvwm man pages
as HTML. Anything we can come up with that renders HTML
is good with me.

That's definitely an output format we'll be doing, even with mdoc---to
lose that would be irritating to say the least.

Post by Dan Espen
I want to mention, when I wrote F_CMD_ARGS,
one of the things I had in mind was to put function
documentation in the .c files. I envisioned some kind of
extract run generating the actual man page input.
I was trying to make the functions easy to find by giving
them a uniform appearance.

Interesting. Whilst I don't like macros in place of formal function
arguments myself, I can see why you did this, Dan. On the point about
documentation, this is precisely what doxygen allows for. We could
always make use of that---and certainly it would be an interesting
excerise to do, as it would help appraise and justify the existing
functions we have, and help identify any potential cleanups, etc.

I'll add this to the TODO for consideration.

Thanks. :)

-- Thomas Adam

--
"Deep in my heart I wish I was wrong. But deep in my heart I know I am
not." -- Morrissey ("Girl Least Likely To" -- off of Viva Hate.)

Dominik Vogt

2014-08-25 21:43:13 UTC

That's definitely an output format we'll be doing, even with mdoc---to
lose that would be irritating to say the least.

Interesting. Whilst I don't like macros in place of formal function
arguments myself, I can see why you did this, Dan.

Well, for me the macros F_CMD_ARGS and F_PASS_ARGS helped me a lot,
even without documnetation. Before we had them, you had to change
more than 300 funtion declarations and function headers and maybe
1000 argument lists in internal calls when you added or removed a
command argument. Now, I could add in another command argument
and had to change only a couple of calls that are too specific to
use F_PASS_ARGS. They have saved me many, many hours of boring,
tedious and error prone work and have definitely improved the
overall code quality.

Apart from that, I'm not a big fan of macros that contain more
than a constant or a very simple expressions. But sometimes they
can really help.

Post by Thomas Adam
On the point about
documentation, this is precisely what doxygen allows for. We could
always make use of that---and certainly it would be an interesting
excerise to do, as it would help appraise and justify the existing
functions we have, and help identify any potential cleanups, etc.

I've worked with Doxygen on several occations but never got fond
of it. People forget to update the source code documentation, and
summaries of whole modules are hardly ever written. Often you end
up with a loose collection of poorly maintained function
descriptions without the correllations documented. Personally I
find it easier to remember writing decent documentation when it's
all in a single place (one of my main woes with the xml files).

Ciao

Dominik ^_^ ^_^

--
Dominik Vogt

Javier Fernandez

2014-08-25 19:01:16 UTC

Post by Glenn Golden
troff. Ancient perhaps, but even today, nothing beats it, IMO. (The TeX/latex
family seems to be the only serious competitor, and colleagues over the years
familiar with with both seem to like them about equally.)

What do you think of GNU/texinfo?

PS: Don't misinterpret me. I think troff is ok. I see no need to
move away from troff. I am just curious on your opinions on the
improvements texinfo might give.

Thomas Adam

2014-08-25 20:31:41 UTC

Post by Javier Fernandez

What do you think of GNU/texinfo?
PS: Don't misinterpret me. I think troff is ok. I see no need to
move away from troff. I am just curious on your opinions on the
improvements texinfo might give.

I personally dislike it, especially since the front-end viewers for info
pages are incredibly unintuitive. I'm unclear how widespread texinfo is
outside of the GNU world, but it seems still to be something of a curio;
and that manpages have more or less surpassed info pages.

-- Thomas Adam

--
"Deep in my heart I wish I was wrong. But deep in my heart I know I am
not." -- Morrissey ("Girl Least Likely To" -- off of Viva Hate.)

Bert Geens

2014-08-26 15:32:47 UTC

Note that the following should not be taken as a plea for Fvwm to switch
to TexInfo, I merely wanted to address some of the points Thomas made.

Also note that I so far have no experience writing manpages nor TexInfo
documents, so the above is purely a "client side" view on things.