This mailing list is for discussing NetBSD docs

Mark Weinem | 2 Apr 2007 00:41

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 2007 01:25

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 2007 08:36

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)

Mark Weinem | 2 Apr 2007 16:10

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)

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

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 2007 16:50

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 2007 17:12

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)

Hubert Feyrer | 2 Apr 2007 16:19

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

Jeremy C. Reed | 2 Apr 2007 15:48

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 2007 16:06

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>

Andrew Ball | 2 Apr 2007 15:28

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 2007 16:04

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)

haad | 2 Apr 2007 11:31

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)

Return

Return to gmane.os.netbsd.documentation.

Search Archive

Language

Change language

Options

Current view: Threads only / Showing only 20 lines / Not hiding cited text.
Change to All messages, whole messages, or hide cited text.

Post a message
NNTP Newsgroup
Classic Gmane web interface
XML

XML

RSS Feed
List Information

About Gmane