Re: migrating the NetBSD users guide to the wiki

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

Sevan Janiyan writes:
> On 03/05/2019 23:06, Leonardo Taccari wrote:
> > 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.
>
> How do you read the wiki?
>

Mostly via a web browser, and when searching via a recursive grep in
wikisrc repository.

> > 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?
>
> The wiki is not multiformat.
>

Yes, while that's probably okay for most of htdocs I think that's
a big limitation of eventually using wikisrc for the guide.

> > 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).
>
> These are nothing to do with the format which is inflicted on the editor
> and though I haven't consulted admins, there is no reason why the
> wikisrc repo couldn't be made available. I have asked Joerg if it could
> be part of the conversion process - that would also make it available on
> $otherscm mirror sites.
>

Yes, but right now it has something to do regarding the lower barrier.
ATM on wikisrc the contributor needs to fetch manually each wiki
page, keep it as .orig file and then share the patch.

> [...]
> >  - 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.
>
> I think inflicting hand editing XML on people is a cruel exercise. I
> would like to add content to the guide but I do not want to edit docbook
> XML.
>

Apart lengthier tags I don't think editing XML is so much more
terrible than editing markdown.  www@ can also help to integrate
possible contributions in text format.