Re: migrating the NetBSD users guide to the wiki

[Leonardo Taccari <leot%NetBSD.org@localhost>]

Sevan Janiyan writes:
> Hello,

Hello Sevan,

> I've been trying to tidy up the wiki to cull old or duplicate content
> which we inherited from wiki.netbsd.se with the intention of adding
> useful info to the NetBSD guide and with that rejuvenating some of the
> content there before bringing the guide back to the wiki.
>

Thanks for improving the wiki!

> I stumbled across a copy of the guide in the wikisrc already which I'd
> not noticed before as I'd been mostly looking at the tutorials
> directory. The end result of the wikified version seems ok, what we lose
> in the power of docbook we gain in lower barrier to entry for contributions.
>
> docbook
> pros: multi format output, pro authoring platform for writing books
> cons: xml, pkgsrc/meta-pkgs/netbsd-www dependency list
>
> wiki
> pros: simple format (markdown)
> cons: no multi format output
>
> I was wondering if I did the work to reconvert (resync?) the NetBSD
> guide from docbook to the wiki, could we delete the docbook version?
> [...]

I find `The NetBSD Guide', `The pkgsrc guide' and `NetBSD Internals'
as books.  As them IMHO is very important to have a printer friendly
version of them (when I first started using NetBSD and pkgsrc one
of the first thing that I have done was printing both guides).

These days, especially for reference, I mostly consult their .txt
version by just opening netbsd.txt or pkgsrc.txt via the $PAGER.

If guides are migrated to wikisrc is it possible to:

 - have a PDF version of them?
 - have a text version of them?
 - have a single HTML page version of them?

Regarding the lower barrier, I think that as they are now - especially
for possible contributors without commit access - probably editing .xml
has several advantages as well:

 - repositories are available via anoncvs.n.o (that's not the case of
   wikisrc AFAIK).
 - when editing the .xml-s it is possible to directly check the results
   by just regenerating the .html or other formats via make.
 - IME when editing wikisrc markdown and using non trivial formatting it
   often violate the POLA.  When making XML formatting mistakes most of
   the times useful error messages are provided.