Re: migrating the NetBSD users guide to the wiki

[John Nemeth <jnemeth%cue.bc.ca@localhost>]

On May 4, 12:33am, Sevan Janiyan wrote:
} 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?
} 
} > 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.
} 
} > 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.
} 
} >  - when editing the .xml-s it is possible to directly check the results
} >    by just regenerating the .html or other formats via make.
} 
} It is possible to preview the results with the wiki too though I don't
} recall the details.
} 
} >  - 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.

     I disagree.  In fact, I much prefer working with docbook
(docbook is not raw XML) than markdown since it is much easier to
understand, and figure out what the end result should be.  Hand
editing docbook (other than being more strict) is no worse then
hand editing HTML.  Of course, I have never used a webpage generator
and have always hand edited any page that I've worked on.

}-- End of excerpt from Sevan Janiyan