Re: skaware manpages?
On Fri, Aug 21, 2015 at 4:33 PM, Laurent Bercot wrote: > On 22/08/2015 01:03, Buck Evan wrote: >> >> Actually, apparently HTML is the preferred format, so we're good. >> https://www.debian.org/doc/debian-policy/ch-docs.html#s12.4 > > > Yeah, in the 12.1 section they still say that they consider the lack > of a manpage for a binary as a bug. >.> > If they'll take stubs, that's probably your best option. > I'm going to take this moment to say that I'm really happy that, for all their Makefile style guides and build location stuff, the FreeBSD ports guidelines don't care at all about how documentation is offered. Speaking of which, I've managed to get caught up with the current release versions. There was a period where I was lagging about 1-2 release versions behind due to slowness on the part of the port integrators, but they seem to have picked up the pace now that 10.2 is out. Cheers! -- "If the doors of perception were cleansed every thing would appear to man as it is, infinite. For man has closed himself up, till he sees all things thru' narrow chinks of his cavern." -- William Blake
Re: skaware manpages?
On 22/08/2015 01:03, Buck Evan wrote: Actually, apparently HTML is the preferred format, so we're good. https://www.debian.org/doc/debian-policy/ch-docs.html#s12.4 Yeah, in the 12.1 section they still say that they consider the lack of a manpage for a binary as a bug. >.> If they'll take stubs, that's probably your best option. -- Laurent
Re: skaware manpages?
Actually, apparently HTML is the preferred format, so we're good. https://www.debian.org/doc/debian-policy/ch-docs.html#s12.4 On Fri, Aug 21, 2015 at 3:57 PM, Buck Evan wrote: > Sounds good. > I'll probably put some stub manpages with the link to the web as you > suggest. > If Debian won't stomach it, I'll then try to reformat your html in a > script. > > The mapping from markdown to html is quite simple. > I may redo one of your pages as markdown to give you something more > concrete to hate. > > > > On Fri, Aug 21, 2015 at 2:34 PM, Laurent Bercot > wrote: > >> On 21/08/2015 22:10, Buck Evan wrote: >> >>> @Laurent: What's your take on man pages? >>> >> >> Short version: I like them, as long as I don't have to write them >> or move a finger to generate them. >> >> Long version: >> >> I honestly believe man pages are obsolete. They were cool in the >> 90's when they were all we had; but today, *everyone* has a web >> browser, and can look at HTML documentation. Even if they don't have >> an Internet access. >> >> I still find myself typing "man" sometimes. It's a reflex because >> I'm a dinosaur. But if it doesn't work, I don't mind: the documentation >> *is* somewhere, I just have to grab my browser. >> GNU people never write man pages. They write info pages. That blows, >> and I'd rather look at the source code to understand what it does >> than install and run an info client. Fortunately, the documentation is >> also available in HTML, so I go read the doc on the web. When I was >> writing my build system, I was very, very glad that the make manual >> was available in HTML; I spent hours on that document, with several >> tabs open at various places - browsers are user-friendly. Much more >> so than xterms running a rich text visualizer. >> >> So, info2html, man2html, or SGML/DocBook source, and so on? >> Well, as much as I love Unix, one aspect of it that I really dislike >> is the proliferation of markup languages. nroff is one, info is >> another one, pod is one, and so on; I've stopped counting the number >> of initiatives aiming to produce rich text. I've always managed to >> avoid learning those languages. I've only learned LaTeX and HTML; >> I quickly forgot the former as soon as I was out of academia and >> didn't need it anymore, and I only memorized the latter because it's >> ubiquitously useful. Markup, or markdown, languages, are really >> not my cup of tea; and if I didn't learn nroff in 1995, when there >> actually was a serious use case for it, I'm definitely not going >> to learn it today. >> >> I'll keep providing HTML docs, and only HTML docs. If you want to >> provide man pages, you're very welcome to it, as long as I don't >> have to do anything. :P >> >> Since I don't believe in the future of man pages, I even think >> that only providing stub man pages would be perfectly acceptable: >> in the man page, only have a link to the relevant HTML document, >> on the local machine as well as on the Web. >> >> If you don't like stubs, heinous scripts should produce more >> acceptable results than you think. I try to keep a reasonably >> regular format for the doc pages of executables; I don't mind >> enforcing the regularity a bit more seriously if it makes your >> scripts easier or more accurate. >> >> -- >> Laurent >> >> >
Re: skaware manpages?
Sounds good. I'll probably put some stub manpages with the link to the web as you suggest. If Debian won't stomach it, I'll then try to reformat your html in a script. The mapping from markdown to html is quite simple. I may redo one of your pages as markdown to give you something more concrete to hate. On Fri, Aug 21, 2015 at 2:34 PM, Laurent Bercot wrote: > On 21/08/2015 22:10, Buck Evan wrote: > >> @Laurent: What's your take on man pages? >> > > Short version: I like them, as long as I don't have to write them > or move a finger to generate them. > > Long version: > > I honestly believe man pages are obsolete. They were cool in the > 90's when they were all we had; but today, *everyone* has a web > browser, and can look at HTML documentation. Even if they don't have > an Internet access. > > I still find myself typing "man" sometimes. It's a reflex because > I'm a dinosaur. But if it doesn't work, I don't mind: the documentation > *is* somewhere, I just have to grab my browser. > GNU people never write man pages. They write info pages. That blows, > and I'd rather look at the source code to understand what it does > than install and run an info client. Fortunately, the documentation is > also available in HTML, so I go read the doc on the web. When I was > writing my build system, I was very, very glad that the make manual > was available in HTML; I spent hours on that document, with several > tabs open at various places - browsers are user-friendly. Much more > so than xterms running a rich text visualizer. > > So, info2html, man2html, or SGML/DocBook source, and so on? > Well, as much as I love Unix, one aspect of it that I really dislike > is the proliferation of markup languages. nroff is one, info is > another one, pod is one, and so on; I've stopped counting the number > of initiatives aiming to produce rich text. I've always managed to > avoid learning those languages. I've only learned LaTeX and HTML; > I quickly forgot the former as soon as I was out of academia and > didn't need it anymore, and I only memorized the latter because it's > ubiquitously useful. Markup, or markdown, languages, are really > not my cup of tea; and if I didn't learn nroff in 1995, when there > actually was a serious use case for it, I'm definitely not going > to learn it today. > > I'll keep providing HTML docs, and only HTML docs. If you want to > provide man pages, you're very welcome to it, as long as I don't > have to do anything. :P > > Since I don't believe in the future of man pages, I even think > that only providing stub man pages would be perfectly acceptable: > in the man page, only have a link to the relevant HTML document, > on the local machine as well as on the Web. > > If you don't like stubs, heinous scripts should produce more > acceptable results than you think. I try to keep a reasonably > regular format for the doc pages of executables; I don't mind > enforcing the regularity a bit more seriously if it makes your > scripts easier or more accurate. > > -- > Laurent > >
Re: skaware manpages?
On 21/08/2015 22:10, Buck Evan wrote: @Laurent: What's your take on man pages? Short version: I like them, as long as I don't have to write them or move a finger to generate them. Long version: I honestly believe man pages are obsolete. They were cool in the 90's when they were all we had; but today, *everyone* has a web browser, and can look at HTML documentation. Even if they don't have an Internet access. I still find myself typing "man" sometimes. It's a reflex because I'm a dinosaur. But if it doesn't work, I don't mind: the documentation *is* somewhere, I just have to grab my browser. GNU people never write man pages. They write info pages. That blows, and I'd rather look at the source code to understand what it does than install and run an info client. Fortunately, the documentation is also available in HTML, so I go read the doc on the web. When I was writing my build system, I was very, very glad that the make manual was available in HTML; I spent hours on that document, with several tabs open at various places - browsers are user-friendly. Much more so than xterms running a rich text visualizer. So, info2html, man2html, or SGML/DocBook source, and so on? Well, as much as I love Unix, one aspect of it that I really dislike is the proliferation of markup languages. nroff is one, info is another one, pod is one, and so on; I've stopped counting the number of initiatives aiming to produce rich text. I've always managed to avoid learning those languages. I've only learned LaTeX and HTML; I quickly forgot the former as soon as I was out of academia and didn't need it anymore, and I only memorized the latter because it's ubiquitously useful. Markup, or markdown, languages, are really not my cup of tea; and if I didn't learn nroff in 1995, when there actually was a serious use case for it, I'm definitely not going to learn it today. I'll keep providing HTML docs, and only HTML docs. If you want to provide man pages, you're very welcome to it, as long as I don't have to do anything. :P Since I don't believe in the future of man pages, I even think that only providing stub man pages would be perfectly acceptable: in the man page, only have a link to the relevant HTML document, on the local machine as well as on the Web. If you don't like stubs, heinous scripts should produce more acceptable results than you think. I try to keep a reasonably regular format for the doc pages of executables; I don't mind enforcing the regularity a bit more seriously if it makes your scripts easier or more accurate. -- Laurent
skaware manpages?
@Laurent: What's your take on man pages? I'd like to provide some in my packaging, particularly for s6, but there's only the html docs provided. I could *possibly* write some heinous script to convert those simple html docs to man page format, but it's unlikely to produce acceptable results. There are tools to convert markdown to manpage format, and of course to convert markdown to html. If we maintained the docs as markdown, it would solve the problem without maintaining two copies of the docs in two formats. Of course there are more solutions. Let me know how / if you'd like to see this solved.
