Re: Some suggestions about PKGNG documentation
On Sun, 6 Jul 2014, Patrick Powell wrote: On 07/05/14 03:18, Mike Brown wrote: Warren Block wrote: The documentation team has a standing offer to either assist with markup or accept content-only submissions and do the markup on them. That's good to know. I was under the impression it had to be submitted as DocBook XML. Thanks! OK. Its been 10 years since I lasted looked at the FBSD documents. Nowever, I know SGML, XML, and have written documents in them. 1. Point me to the source of one of the documents as a starting point. 2. Point me to the tools that I need to use to massage the document. (There used to be a Documenter's Handbook, is it still around?) I will take one of these documents as a starting point and then update it. HOWEVER... I am hoping that one of the document team will 'proof' this for format and content. The books and articles are in DocBook XML 5. http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/index.html Chapter 9 shows examples of DocBook markup. Articles are simpler than books. For example: http://svnweb.freebsd.org/doc/head/en_US.ISO8859-1/articles/cups/article.xml?revision=44687view=markup ___ freebsd-ports@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-ports To unsubscribe, send any mail to freebsd-ports-unsubscr...@freebsd.org
Re: Some suggestions about PKGNG documentation
On 07/05/14 03:18, Mike Brown wrote: Warren Block wrote: The documentation team has a standing offer to either assist with markup or accept content-only submissions and do the markup on them. That's good to know. I was under the impression it had to be submitted as DocBook XML. Thanks! ___ freebsd-ports@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-ports To unsuXMbscribe, send any mail to freebsd-ports-unsubscr...@freebsd.org OK. Its been 10 years since I lasted looked at the FBSD documents. Nowever, I know SGML, XML, and have written documents in them. 1. Point me to the source of one of the documents as a starting point. 2. Point me to the tools that I need to use to massage the document. (There used to be a Documenter's Handbook, is it still around?) I will take one of these documents as a starting point and then update it. HOWEVER... I am hoping that one of the document team will 'proof' this for format and content. ___ freebsd-ports@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-ports To unsubscribe, send any mail to freebsd-ports-unsubscr...@freebsd.org
Re: Some suggestions about PKGNG documentation
On Fri, Jul 04, 2014 at 07:00:00PM -0600, Mike Brown wrote: After starting down this road, you may decide it's less of an ordeal just to write something yourself and put it up on your own blog. :/ There are those of us who will do our best to pick up changes and run with them. mcl ___ freebsd-ports@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-ports To unsubscribe, send any mail to freebsd-ports-unsubscr...@freebsd.org
Re: Some suggestions about PKGNG documentation
Warren Block wrote: The documentation team has a standing offer to either assist with markup or accept content-only submissions and do the markup on them. That's good to know. I was under the impression it had to be submitted as DocBook XML. Thanks! ___ freebsd-ports@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-ports To unsubscribe, send any mail to freebsd-ports-unsubscr...@freebsd.org
Re: Some suggestions about PKGNG documentation
Patrick Powell wrote: TUTORIAL: The Savant's Guide To Ports, Packages, PkgNG Try to put a lot of the information about pkgng, repositories, etc. in a single place. I suggest a tutorial format, rather than a user manual format, with references to the various man pages, other documents, etc. Your suggestions sound good to me. Unfortunately, it's not like there's a team of tech writers sitting around waiting for suggestions of things to write and put into the docs. Rather, updating pretty much anything in the documentation -- or the ports for that matter -- requires suggesting the actual changes you want in the form of patches that replace the existing content with your version. http://lists.freebsd.org/mailman/listinfo/freebsd-doc http://www.freebsd.org/docproj/ http://www.freebsd.org/doc/en/books/fdp-primer/book.html After starting down this road, you may decide it's less of an ordeal just to write something yourself and put it up on your own blog. :/ ___ freebsd-ports@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-ports To unsubscribe, send any mail to freebsd-ports-unsubscr...@freebsd.org
Re: Some suggestions about PKGNG documentation
On Fri, 4 Jul 2014, Mike Brown wrote: Patrick Powell wrote: TUTORIAL: The Savant's Guide To Ports, Packages, PkgNG Try to put a lot of the information about pkgng, repositories, etc. in a single place. I suggest a tutorial format, rather than a user manual format, with references to the various man pages, other documents, etc. Your suggestions sound good to me. Unfortunately, it's not like there's a team of tech writers sitting around waiting for suggestions of things to write and put into the docs. Rather, updating pretty much anything in the documentation -- or the ports for that matter -- requires suggesting the actual changes you want in the form of patches that replace the existing content with your version. The documentation team has a standing offer to either assist with markup or accept content-only submissions and do the markup on them. Clear, useful instructions are the difficult part to create. It helps if the writer is familiar with existing work like the Handbook, but is not required. After starting down this road, you may decide it's less of an ordeal just to write something yourself and put it up on your own blog. :/ It's sometimes easier to do that, but fewer people benefit. ___ freebsd-ports@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-ports To unsubscribe, send any mail to freebsd-ports-unsubscr...@freebsd.org
