Mark Weinem | 2 Apr 00:41 2007
Picon

Re: why XML?

James K. Lowden wrote:

> How do you define a URL in mdoc?  Does it become an HREF anchor when
> converted to HTML?  What about a GUI component?  How do you include a
> graphic?
>
>>> If folks want more structured (and truly structured) documentation
>>> then I could only recommend Lout (pkgsrc/textproc/lout) as it is light
>>> years beyond anything-TeX or troff-like and still light years beyond
>>> anything-ML too.
>
> I don't understand how you can recommend it.  The PDF backend is
> officially deprecated, and I see no HTML backend.
> [...]

sorry, the quotes are from Greg A. Woods. I'm only the forwarder, and i
have no detailed knowledge about Lout or groff.

How about "AsciiDoc"? It can produce HTML, PDF and DocBook document
types.

 	http://www.methods.co.nz/asciidoc/index.html

> The evidence stands against you, though.  Many very large documentation
> projects rely on DocBook.

Hm, if only many projects rely on but not all - what alternatives do
they use instead of DocBook?

> DocBook is neither an accident nor a fad.  It demonstrably yields good
(Continue reading)

Greg A. Woods | 2 Apr 01:25 2007
X-Face

Re: why XML?

At Mon, 2 Apr 2007 00:41:53 +0200 (CEST), Mark Weinem wrote:
Subject: Re: why XML? 
> 
> How about "AsciiDoc"? It can produce HTML, PDF and DocBook document
> types.
> 
>  	http://www.methods.co.nz/asciidoc/index.html

AsciiDoc reminds me far too much of being the same kind of hack as Henry
Spencer's AWF is:

	http://www.isc.org/sources/utils/text/awf.php

If one wants clearly readable, easily maintained, easily parsed,
structured documents suitable from everything from business cards to
entire books, then Lout really is the best thing I've seen to date (and
I've been looking at and for such tools for decades now).

HOWEVER, for NetBSD, with a _heavy_ investment already made in mdoc(7)
formatted documents, I would be quite happy to stick with that.  We
already have groff maintained in-tree, and we'll need it for the
foreseeable future anyway.  It's easy enough to use and it is very well
understood too.

--

-- 
						Greg A. Woods

H:+1 416 218-0098 W:+1 416 489-5852 x122 VE3TCP RoboHack <woods <at> robohack.ca>
Planix, Inc. <woods <at> planix.com>       Secrets of the Weird <woods <at> weird.com>
(Continue reading)

Przemysław Pawełczyk | 2 Apr 08:36 2007
Picon

7 points user's memo (was why XML?)

On Sun, 01 Apr 2007 19:25:32 -0400
"Greg A. Woods" <woods <at> planix.com> wrote:

> If one wants clearly readable, easily maintained, easily parsed,
> structured documents suitable from everything from business cards to
> entire books, then Lout really is the best thing I've seen to date
> (and I've been looking at and for such tools for decades now).
>
> HOWEVER, for NetBSD, with a _heavy_ investment already made in mdoc(7)
> formatted documents, I would be quite happy to stick with that.  We
> already have groff maintained in-tree, and we'll need it for the
> foreseeable future anyway.  It's easy enough to use and it is very
> well understood too.
Hi,

The whole disscusion on NetBSD documentation was branched into
several topics nearly from the begining. Now I understand we went
thru following salient point:

1) wrong WWW layout
2) outdated docu-pages
3) weak cooperation with community
4) unefficient docu-page creation tools

A lot of steam was released but we are still in the same dock. This way
we can argue for ages.

Could someone summerize what convenient tools for XML (present),
nroff/mdoc (former), and Lout (recommended) formats available for
NetBSD user willing to write docu-pages? When I write docu-pages I
(Continue reading)

haad | 2 Apr 11:31 2007
Picon

Re: 7 points user's memo (was why XML?)


Przemysław Pawełczyk wrote:
> On Sun, 01 Apr 2007 19:25:32 -0400
> "Greg A. Woods" <woods <at> planix.com> wrote:
> 
>> If one wants clearly readable, easily maintained, easily parsed,
>> structured documents suitable from everything from business cards to
>> entire books, then Lout really is the best thing I've seen to date
>> (and I've been looking at and for such tools for decades now).
>>
>> HOWEVER, for NetBSD, with a _heavy_ investment already made in mdoc(7)
>> formatted documents, I would be quite happy to stick with that.  We
>> already have groff maintained in-tree, and we'll need it for the
>> foreseeable future anyway.  It's easy enough to use and it is very
>> well understood too.
> Hi,
> 
> The whole disscusion on NetBSD documentation was branched into
> several topics nearly from the begining. Now I understand we went
> thru following salient point:
> 
> 1) wrong WWW layout

> 2) outdated docu-pages
> 3) weak cooperation with community
> 4) unefficient docu-page creation tools

4) this is your opinion from my point of view they are efficient.

> A lot of steam was released but we are still in the same dock. This way
(Continue reading)

Andrew Ball | 2 Apr 15:28 2007

Re: 7 points user's memo (was why XML?)


Hello Przemysl/aw

  PP> A lot of steam was released but we are still in the same dock.
    > This way we can argue for ages.

This is just like in a meeting where ideas are proposed and then
rejected.  It may /seem/ like no progress has been made, but in truth
participants are in a subtly different position because everyone knows
what was discussed and that can shape future thinking. In an effective
meeting each participant has to understand that "no" can be a valid
answer and (except in the rare extreme case) try to respect the
consensus.

  PP> Where, what, in what format, etc.

I think the "in what format" has been asked and answered, although
there's probably always room for discussion of potentially useful
tools.

  PP> I can create new WWW with NetBSD contents ina few days.  It's no
    > problem as I designed and created numerous WWWs...

I've given people a solid grounding in HTML in a one hour class and
they've gone on to develop their own Web sites. It's a useful, but not
exremely rare skill.  Being able to write effective copy is another
useful skill.  The combination of those is probably more unusual, but
teamwork can help there.

  PP> For the last time I suggest you a change. No threat, but result
(Continue reading)

Przemysław Pawełczyk | 2 Apr 16:04 2007
Picon

Re: 7 points user's memo (was why XML?)

On Mon, 2 Apr 2007 13:28:19 -0000 (GMT)
"Andrew Ball" <aball <at> students.prairiestate.edu> wrote:

> This is just like in a meeting where ideas are proposed and then
> rejected.  It may /seem/ like no progress has been made, but in truth
> participants are in a subtly different position because everyone knows
> what was discussed and that can shape future thinking. In an effective
> meeting each participant has to understand that "no" can be a valid
> answer and (except in the rare extreme case) try to respect the
> consensus.

Hi,

Not only the "participant has to" but "he does" understand. "No" has the
same meaning (sometimes positive) as "yes" (seometimes negative). I know
that.

> I think the "in what format" has been asked and answered, although
> there's probably always room for discussion of potentially useful
> tools.
It wasn't. I haven't seen "top brass names" in the following
discussion. Everyone said aloud his opinion and that's all. Yeah, I
should noticed from the lack of any "decision" that "what is" will be
continued.

>   PP> I can create new WWW with NetBSD contents ina few days.  It's no
>     > problem as I designed and created numerous WWWs...
>
> I've given people a solid grounding in HTML in a one hour class and
> they've gone on to develop their own Web sites. It's a useful, but not
(Continue reading)

Jeremy C. Reed | 2 Apr 15:48 2007
Picon

Re: 7 points user's memo (was why XML?)

On Mon, 2 Apr 2007, Przemys~Baw Pawe~Bczyk wrote:

> A few days ago Jeremy C. Reed created new page in Wiki.

What is this? What URL? (Or are you referring to the "Recommended 
systems"?)

> Sporadic, ad hoc activity tailored to suddenly emerging circumstations 
> aka needs. But without vision for Wiki or NetBSD docu as a whole. No 
> wonder some of you (me for sure) are discourage to write. Where, what, 
> in what format, etc.

  Jeremy C. Reed
Przemysław Pawełczyk | 2 Apr 16:06 2007
Picon

Re: 7 points user's memo (was why XML?)

On Mon, 2 Apr 2007 08:48:46 -0500 (CDT)
"Jeremy C. Reed" <reed <at> reedmedia.net> wrote:

>
> > A few days ago Jeremy C. Reed created new page in Wiki.
>
> What is this? What URL? (Or are you referring to the "Recommended
> systems"?)

Yes, I did.

pp
--
Przemysław Pawełczyk <pp <at> kv.net.pl>
Mark Weinem | 2 Apr 16:10 2007
Picon

Re: 7 points user's memo

On Mon, 2 Apr 2007, Przemysaw Paweczyk wrote:

> 1) wrong WWW layout

might be - but there is no "right" layout!

> 2) outdated docu-pages

Please list the outdated docs and the updates you need.
We will then help to update them.

> 3) weak cooperation with community

I don't understand this: what is the community? Community of users? The
submitters, developers and maintainers are the users! Any separation
between NetBSD users and doers is IMHO a deception.

> 2) in what field (4 points above) can we succeed soon?

updates, new docs, submitting patches (or at least drafts).

> let me say first that we ended now with no changes.

What did you expect after only a few days of discussion?

> A few days ago Jeremy C. Reed created new page in Wiki. Sporadic, ad
> hoc activity tailored to suddenly emerging circumstations aka needs.

Please, if you want a change to the wiki page discuss it with Jeremy. Or
get in conact with Zafer if you want general wiki changes. Every wiki
(Continue reading)

Hubert Feyrer | 2 Apr 16:19 2007
Picon

Re: 7 points user's memo

On Mon, 2 Apr 2007, Mark Weinem wrote:
> No, for the users of NetBSD! So please go for it and setup the "NetBSD
> Community Documentation Project". Don't wait for elections, voting
> results, "visions" or orders from official parties. Helpful ressources
> like the Wiki, the "NetBSD News Beat" or "The NetBSD CVS Digest" would
> not exist if their creators have waited for consent, votes or
> directives.

Seconded.
Doing gets things done, bitching doesn't.

  - Hubert

Przemysław Pawełczyk | 2 Apr 16:30 2007
Picon

Re: 7 points user's memo

On Mon, 2 Apr 2007 16:10:05 +0200 (CEST)
Mark Weinem <mark.weinem <at> alumni.uni-due.de> wrote:

> might be - but there is no "right" layout!

I should say "less convenient" layout. Pardon.

> > 2) outdated docu-pages
>
> Please list the outdated docs and the updates you need.
> We will then help to update them.
I recapped your words.

> > 3) weak cooperation with community
>
> I don't understand this: what is the community? Community of users?
> The submitters, developers and maintainers are the users! Any
> separation between NetBSD users and doers is IMHO a deception.
Maybe. But look on software project. There is a team of developers,
analysts, and managers and on the other side a user in a form of
another team of managers, workers, and computer maintainers. The two
teams have to work out common project. For users, __not for
themselves__. Do you see the division? Woild you call it deception?

> > let me say first that we ended now with no changes.
> What did you expect after only a few days of discussion?
Your experience should prompt you right answer.

> > A few days ago Jeremy C. Reed created new page in Wiki. Sporadic, ad
> > hoc activity tailored to suddenly emerging circumstations aka needs.
(Continue reading)

Jeremy C. Reed | 2 Apr 16:50 2007
Picon

Re: 7 points user's memo

On Mon, 2 Apr 2007, Przemys~Baw Pawe~Bczyk wrote:

> > > A few days ago Jeremy C. Reed created new page in Wiki. Sporadic, ad
> > > hoc activity tailored to suddenly emerging circumstations aka needs.
> 
> I got nothing against Jeremy! I only wanted to show you "a mechanism",
> a habit of doing things ad hoc.

Are you complaining that I am using a wiki as a wiki? Are you suggesting 
that I shouldn't have started that simple wiki page for my topic?

"Ad hoc" seems appropriate here. I just can't tell if you are being 
negative or positive.

...

> > netbsd.org has already to many (and to nested) links and maybe also to
> > many pages. So what comes next, all the links to news sites, digests,
> > IRC channels, wikipedia articles and web forums?
> 
> You missed one point where I proposed to move some pages from NetBSD to
> wiki. Once to relieve NetBSD, twice, to shore up wiki.

  Jeremy C. Reed
Przemysław Pawełczyk | 2 Apr 17:12 2007
Picon

Re: 7 points user's memo

On Mon, 2 Apr 2007 09:50:32 -0500 (CDT)
"Jeremy C. Reed" <reed <at> reedmedia.net> wrote:

> > > > A few days ago Jeremy C. Reed created new page in Wiki.
> > > > Sporadic, ad hoc activity tailored to suddenly emerging
> > > > circumstations aka needs.
> >
> > I got nothing against Jeremy! I only wanted to show you "a
> > mechanism", a habit of doing things ad hoc.
>
> Are you complaining that I am using a wiki as a wiki? Are you
> suggesting that I shouldn't have started that simple wiki page for my
> topic?

95% of you (plural) are so overly touchy that for 95% of our talks I
explain that "I am not a camel" (Polish saying). It also means that
only 5% read _what_ I want to impart, and not paying attention to
trifles.

1) I'm not complaining that you are using wiki.
2) I ain't suggesting that you "shouldn't started that simple wiki page"
3) I only claim that as the page is not available from Wiki's menu but
from separate address, then this alone proves that the objective page
was created ad hoc, as a response to Jeremy C. Reed needs, and not as a
result of comprehensive policy concerning development of the
aforementioned wiki.

> "Ad hoc" seems appropriate here. I just can't tell if you are being
> negative or positive.
Negative. Let's all of us start creating wiki pages, ad hoc. Who will
(Continue reading)

Andrew Ball | 2 Apr 17:12 2007

Re: 7 points user's memo

Hello Przemysl/aw

  PP> "No" has the same meaning (sometimes positive) as "yes"
    > (seometimes negative). I know that.

The only example that springs to mind is on active-low chip inputs,
and even then it's just because people associate low with "no".  Other
than that I have no idea what you might mean.

  PP> Everyone said aloud his opinion and that's all.

That's often the way that conversation works.

  PP> No, the accent is not on "suggestions" I've made but on the
    > time: "for the last time". In other words I declare that for the
    > last time I submit in the mailing list any idea of mine.

You're not going to write any more?

  PP> And to alleviate the utterance which could sound to many
    > blasphemously :-), I added that "it is not a threat" from my
    > side that "I never ever open my mouth to you" (it is a subtle
    > joke, a self-irony)...

It loses something in translation.

  PP> I don't want to write to ephemeral "www team", but to names
    > "with blood and bones."

I have no idea what that means.
(Continue reading)

Przemysław Pawełczyk | 2 Apr 17:59 2007
Picon

Re: 7 points user's memo

On Mon, 2 Apr 2007 15:12:04 -0000 (GMT)
"Andrew Ball" <aball <at> students.prairiestate.edu> wrote:

> Hello Przemysl/aw
>
>   PP> "No" has the same meaning (sometimes positive) as "yes"
>     > (seometimes negative). I know that.
>
> The only example that springs to mind is on active-low chip inputs,
> and even then it's just because people associate low with "no".  Other
> than that I have no idea what you might mean.

You said the "no" and "yes" have the same weight sometimes (neuron
networks come to my mind). On the other hand "No" can have positive
meaning during e.g. brainstorms (aka vehement discussions). "Positive"
thru the results it brings (nixing errenuous paths) .

>   PP> No, the accent is not on "suggestions" I've made but on the
>     > time: "for the last time". In other words I declare that for the
>     > last time I submit in the mailing list any idea of mine.
> You're not going to write any more?
No, I said I would stop to deliver ideas.

> In the message that I read, Zafar wrote "So it starts to rot",
Right, my fault.

> private message, off-list.  Note that these two have very different
> meanings.
Yes, I know.

(Continue reading)

Andrew Ball | 2 Apr 18:43 2007

Re: 7 points user's memo


Hello Przemysl/aw,

  PP> You said the "no" and "yes" have the same weight
    > sometimes...

You are mistaken.  I never said (or even implied) that here.

  PP> On the other hand "No" can have positive meaning
    > during e.g. brainstorms (aka vehement discussions).

Brainstorms and vehement discussions are two entirely
different animals.

  PP> No, I said I would stop to deliver ideas.

I think that would be a shame, but I think it's especially
important in a community of voluntary involvement to deliver
them tactfully.  Here's an example:-

   NetBSD has worked very well for me over the past ten
   years.  I have noticed that some of the documentation
   seems a little out of date.  My available time is
   limited but if I can give something back to NetBSD by
   helping with the documentation, I am more than willing
   to invest some time.  What can I do to help?

See, I've established that I have some experience with the
operating system, identified an opportunity for improvement
and made an offer to help.  There's no agenda there, no list
(Continue reading)

Daniel de Kok | 2 Apr 23:55 2007
Picon

Re:7 points user's memo (was why XML?)

Przemysław Pawełczyk wrote:
> 1) do we take the status quo for granted?
>
[snip]
> 
> 1) "WWW Team" and "Wiki Team" will be "formally" elected (with
> common sense on mind of course :-) ) with __member names available to
> all__.

That's great and all - have fun with your own revolution. In the end
the WWW team has to answer and handle every e-mail and request to the
www <at>  and mirrors <at>  list. Practically, this means that members of the
WWW team take care of all incoming questions/requests/etc. for a whole
week in turns.

Do you have any idea how many people have the dedication to do this
for years? There has been some fluctuation over the years, but basically
this has been the same team of about five or six persons. Others have
tried this, but it takes a lot of time, love, and dedication to do it
longer than just a few weeks.

Yes, building a website does not take too much work. We are all able
to do that. But we have to handle a tree of hundreds of documents
week after week, month after month, and year after year.

You can help, and new people are invited in the team. But only after
they have contributed a significant amount of work. In this community
you are not judged by the amount you talk, but by the amount you
contribute.

(Continue reading)

Daniel de Kok | 2 Apr 23:30 2007
Picon

Re: why XML?

Mark Weinem wrote:
> Why become set on output if already the *input* doesn't work? I don't
> know if the contributions to the documentation really have decreased.

While this is not really relevant to NetBSD documentation, since we
have a huge body of XML material, I have decided to use Yodl[1] for my
own personal stuff from now on. It feels kind of LaTeX-ish, but is not
tied to printed output. It allows for easy definition of new macros.
Existing macro's are sensible,a nd it has been around for very long,
I am not sure why I ever missed it ;). At the moment there's only a
very version in pkgsrc. I'd grab a new version to get a good impression.

-- Daniel

[1] http://yodl.sourceforge.net/


Gmane