headers
Hubert Feyrer | 1 Dec 2005 07:38

NetBSD 3.0 TODO: documentation updates


As you probably know, NetBSD 3.0 is not far away.
There's a lot of documentation available that hasn't been reviewed
and update for NetBSD 3.0, e.g. the NetBSD guide, and other parts of htdocs.

Things that come to mind are:
  * all of the NetBSD guide at http://www.netbsd.org/guide/en/
  * the pkgsrc guide (which could do with a lot more work; volunteers?)
  * the general NetBSD documentation at
    http://www.netbsd.org/Documentation/
  * The list of devices supported by NetBSD at
    http://www.netbsd.org/Hardware/ (automatic creation of this would be
    nice)
  * htdocs/People and htdocs/Foundation has some funny overlap
  * The gallery could use some looks, see http://www.netbsd.org/gallery/
  * See if the information on your favourite port liked at
    http://www.netbsd.org/Ports/ is still valid
  * Any of the translations of the above

If anyone feels like going through this, drop a short note here & do it.
Feel free to mail me patches for review & commit.

  - Hubert
Permalink | Reply | 1 comment |
headers
Jonathan A. Kollasch | 1 Dec 2005 18:47
Gravatar

Re: NetBSD 3.0 TODO: documentation updates

On Thu, Dec 01, 2005 at 07:38:38AM +0100, Hubert Feyrer wrote:
>  * the general NetBSD documentation at
>    http://www.netbsd.org/Documentation/

I've been working up a patch to update Documentation/network/ipv6,
do I need to worry about other translations?

	Jonathan Kollasch
Permalink | Reply | 0 comments |
headers
Brian | 3 Dec 2005 02:18

Re: NetBSD 3.0 TODO: documentation updates

>  * the general NetBSD documentation at
>    http://www.netbsd.org/Documentation/

If I have the time, I'd be glad to work on Documentation/updating.html,
"Updating a stable NetBSD release".  It's been out of date for a while
now.  Documentation/current is also out of date, though I haven't ever
run current, so I can't really do much there.

--

-- 
http://www.fastmail.fm - The way an email service should be
Permalink | Reply | 752 comments |
headers
Jeremy C. Reed | 3 Dec 2005 02:24

Re: NetBSD 3.0 TODO: documentation updates

On Fri, 2 Dec 2005, Brian wrote:

> If I have the time, I'd be glad to work on Documentation/updating.html,
> "Updating a stable NetBSD release".  It's been out of date for a while
> now.  Documentation/current is also out of date, though I haven't ever
> run current, so I can't really do much there.

Sounds great. Please consider working on and submitting a diff of the 
updating.xml (and not the HTML itself) as this will save us time.

Thanks!

  Jeremy C. Reed

  	  	 	 BSD News, BSD tutorials, BSD links
 	  	 	 http://www.bsdnewsletter.com/
Permalink | Reply | 0 comments |
headers
Hubert Feyrer | 3 Dec 2005 02:45

Re: NetBSD 3.0 TODO: documentation updates

On Fri, 2 Dec 2005, Brian wrote:
>>  * the general NetBSD documentation at
>>    http://www.netbsd.org/Documentation/
>
> If I have the time, I'd be glad to work on Documentation/updating.html,
> "Updating a stable NetBSD release".  It's been out of date for a while
> now.  Documentation/current is also out of date, though I haven't ever
> run current, so I can't really do much there.

Yep - in the long run I think it would be nice to merge this into the 
NetBSD Guide, e.g. either in the "Building the system" section or a 
new, seperate "Updating the system" section.

Feel free to send patches against the XML files to www <at> NetBSD.org and CC: 
me. More hints for htdocs work: http://www.NetBSD.org/developers/.

  - Hubert
Permalink | Reply | 751 comments |
headers
Klaus Heinz | 10 Dec 2005 20:53
Picon

XML and relative paths in htdocs

Hi,

I would like to pick up a thread from earlier this year

  "better integration of news pages for NetBSD and pkgsrc"
  http://thread.gmane.org/gmane.os.netbsd.documentation/969

  [ XML-file with news entries, re-usable in different documents ]

In this case (and in several others, probably) we need a list of
objects which can be used in several documents.
Hiroki Sato already provided some patches to implement this for
htdocs/Changes/*.

Looking at this again, I found we still have at least one problem with
this approach: Today we use <ulink> for cross references / links to
other documents which is fine for absolute URLs. This can fail miserably
if we have relative paths for "url" attributes in an <ulink> element 
and then include such an element in more than one document at different
levels in the directory hierarchy.

If nobody has a better idea, we may have to start using (and converting
existing XML files to use) <olink> elements. I had a brief look at how
<olink> works (http://www.sagehill.net/docbookxsl/Olinking.html#LinkBetweenDocs)
and I think it needs a bit of infrastructure to determine the relative
paths during XSLT transformation. It seems to be somewhat similar to
the layout.xml/autolayout.xml scheme.

Instead of using
  <ulink url="../../Bla/foo.html#some.anchor.id" />
(Continue reading)

Permalink | Reply | 7 comments |
headers
Hubert Feyrer | 10 Dec 2005 21:44

Re: XML and relative paths in htdocs

On Sat, 10 Dec 2005, Klaus Heinz wrote:
> Instead of using
>  <ulink url="../../Bla/foo.html#some.anchor.id" />
>
> we would then have
>
>  <olink targetdoc="doc.foo.id" targetptr="some.anchor.id" />

Where does "doc.foo.id" come from?

  - Hubert
Permalink | Reply | 1 comment |
headers
Hubert Feyrer | 10 Dec 2005 22:30
Picon

translation request: de, es, et, f, pl, pt_BR


Dear NetBSD translation team,

a file was moved around on the FTP server recently, which needs update for 
documentation: ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc.tar.gz is 
now known as ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc-current.tar.gz.

In the process of fixing this, I have added two new entities 
&url.pkgsrc.current.tarball; and &filename.pkgsrc.current.tarball;
which map to "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc-current.tar.gz" 
and "pkgsrc-current.tar.gz".

Please update your translations to use these entities, affected files are 
listed below. Take htdocs/Documentation/software/packages.xml as an 
example.

Files that haven't been translated from .list to .xml should get 
translated in this process too, and those that are there should be checked 
that they actually build(!) so I can actually do that change myself next 
time.

If you have questions, feel free to get back to me (preferably only on 
netbsd-docs <at> , sorry for spamming so many lists). If you have something 
to commit, send it to www <at>  and feel free to CC: me.

Thanks for helping out with our documentation!

  - Hubert

Affected files:
(Continue reading)

Permalink | Reply | 0 comments |
headers
Klaus Heinz | 11 Dec 2005 01:00
Picon

Re: XML and relative paths in htdocs

Hubert Feyrer wrote:
> On Sat, 10 Dec 2005, Klaus Heinz wrote:

> > <olink targetdoc="doc.foo.id" targetptr="some.anchor.id" />
> 
> Where does "doc.foo.id" come from?

It's an identifier for the document which we can choose; it probably
should describe the content of the document.
If we keep this identifier the same, we could even move the document
itself to a different directory and the XSLT stylesheets should track
this new location by means of the document database and create new
correct relative "href" attributes.
That's what I meant when I wrote "similar to layout.xml/autolayout.xml".
Of course we must maintain this "document database" file, like we do
with layout.xml, when we move an XML file. I still hope we can automate
this process of maintaining layout.xml (and maybe this other file) some
more.

ciao
     Klaus
Permalink | Reply | 0 comments |
headers
Rui Paulo | 12 Dec 2005 20:32

Re: XML and relative paths in htdocs

On 2005.12.10 20:53:24 +0100, Klaus Heinz wrote:
| Hi,
| 
| I would like to pick up a thread from earlier this year
| 
|   "better integration of news pages for NetBSD and pkgsrc"
|   http://thread.gmane.org/gmane.os.netbsd.documentation/969
| 
|   [ XML-file with news entries, re-usable in different documents ]
| 
| In this case (and in several others, probably) we need a list of
| objects which can be used in several documents.
| Hiroki Sato already provided some patches to implement this for
| htdocs/Changes/*.
| 
| Looking at this again, I found we still have at least one problem with
| this approach: Today we use <ulink> for cross references / links to
| other documents which is fine for absolute URLs. This can fail miserably
| if we have relative paths for "url" attributes in an <ulink> element 
| and then include such an element in more than one document at different
| levels in the directory hierarchy.
| 
| If nobody has a better idea, we may have to start using (and converting
| existing XML files to use) <olink> elements. I had a brief look at how
| <olink> works (http://www.sagehill.net/docbookxsl/Olinking.html#LinkBetweenDocs)
| and I think it needs a bit of infrastructure to determine the relative
| paths during XSLT transformation. It seems to be somewhat similar to
| the layout.xml/autolayout.xml scheme.
| 
| Instead of using
(Continue reading)

Permalink | Reply | 2 comments |

Gmane