Re: Gripes about Pod6 (S26)
a) How many of the gripes are affected by Damian's new draft ? I found many of my pet irritations were eliminated by the new one. b) I suggest that Damian's new draft is committed as S-26 forthwith and development begin on it. c) Some of the comments in threads on documentation have been more aggressive than any of the other perl6 development discussion. More courtesy would be more productive. d) The S-26 document - I think - needs a section at the beginning stating the design goals for the documentation system. Documentation can be written for more than one purpose and not all purposes can be catered for at the same time with a simple specification. By stating goals, it will be clear why and where compromises have to be made. Richard Damian Conway wrote: Carl observed: Partly that is because documentation isn't at the forefront of things that need to be implemented for Perl 6 to be useful, so it's kind of lagging behind the rest. Partly it's because Damian is the owner of that synopsis, and he practices a kind of drive-by-updating to it. As a case in point of this latter effect, the extensive changes made by Damian in August *still* haven't hit the Pugs repo. The latter is entirely true but, fortunately, also very easily remedied. I hereby disclaim all present and future ownership of S26. :-) By all means put the latest update on the repo (or maybe remove S26 entirely), and start redesigning it collaboratively. Please note that I am not in any way upset, angry, petulant, or otherwise disaffected. I only want the very best for every aspect of Perl 6. If the experience of respected and active developers suggests that Pod 6 isn't a step in the right direction, I can only feel disappointed in myself, apologize for my failure, and gratefully turn the task over to those with better ideas and more time and energy to devote to the problem. As regards Pod vs Pandoc (which is pretty clearly the leading contender of the structured text notations), I do think Pod has some decided advantages. For example, I feel it's better to have four basic metasyntaxes (X, =IDENT, :OPTION, #=) and most with identifier-based labels, than to have over two dozen (plus embedded HTML and TeX) all with symbolic labels. I guess I feel that Pandoc/Markdown/ReST/etc. are optimized for writing documentation source, whereas Pod is optimized for reading documentation source. I'm not sorry I aimed for the latter, whatever the deficiencies in the result. Carl also suggested: I think that the future of S26 is very much dependent on whether it'll be able to respond to the needs of Perl 6 developers. Right now it doesn't respond to much of anything. Outwardly this is self-evidently true. One need only look at the (lack of) commit log for S26. :-( Inwardly, something else entirely is happening. A design(er) can only respond effectively when subjected to a clear net force pushing or pulling in some well-defined direction. The redesign of Pod has been subject to an enormous number of such forces. Unfortunately they push and pull it in every possible mutually contradictory direction, thereby producing very little overall impetus. So I would encourage those of you who are going to collectively take over the shepherding of this synopsis to go back through the p6l archives and review the many many posts commenting on and requesting features for Perl 6 documentation. In particular, please look carefully at the very different needs of those who document OO code, procedural code, frameworks, modules, applications, design documents, presentations, and Perl itself. You will find that many of these contributors ignore, discount, or actively disparage the needs of their fellow users. For example, in this very thead: I'm not writing a book, I'm writing code. And if I was writing a book, I wouldn't be dumb enough to write it in POD. Yet what is the Perl documentation itself but a series of book chapters? And surely that documentation is the largest single use of Pod anywhere? Should we not write Perl's own documentation in Perl's own documentation notation? Should we really discourage the use of standard headings to consistently mark the common components of these (and most other) Perl-related documents? I sincerely hope that the future community of designers of Perl 6 's documentation format will find a way to honour and support the very different needs of *all* the creators and users of Perl, not just the needs of the most prominent, or the needs of the most experienced, or the needs of the most loquacious. I have always thought that was the *real* challenge of post-modern language design. Damian
Re: Gripes about Pod6 (S26)
Damian (), Carl (): Partly that is because documentation isn't at the forefront of things that need to be implemented for Perl 6 to be useful, so it's kind of lagging behind the rest. Partly it's because Damian is the owner of that synopsis, and he practices a kind of drive-by-updating to it. As a case in point of this latter effect, the extensive changes made by Damian in August *still* haven't hit the Pugs repo. The latter is entirely true but, fortunately, also very easily remedied. I hereby disclaim all present and future ownership of S26. :-) Thank you. I do want to stress that I, despite my doubts and criticisms in this thread, appreciate all the time and effort you've put into S26. It is *because* I want the best for that synopsis that I brought up the above. Whether the ownership thing was actual or perceived -- and your email indicates the latter -- it did put S26 very much outside of the flow of piecemeal improvements that we take for granted in the other spec files. By all means put the latest update on the repo (or maybe remove S26 entirely), and start redesigning it collaboratively. I now put the latest update on the repo. Please note that I am not in any way upset, angry, petulant, or otherwise disaffected. I only want the very best for every aspect of Perl 6. If the experience of respected and active developers suggests that Pod 6 isn't a step in the right direction, I can only feel disappointed in myself, apologize for my failure, and gratefully turn the task over to those with better ideas and more time and energy to devote to the problem. Again, thanks for your efforts so far. The discussions over the years have shown at least me what an ungrateful task it is to be redesigning Pod for Perl 6. // Carl
Re: Gripes about Pod6 (S26)
On Fri, Feb 12, 2010 at 14:57, Carl Mäsak cma...@gmail.com wrote: Again, thanks for your efforts so far. The discussions over the years have shown at least me what an ungrateful task it is to be redesigning Pod for Perl 6. Yep, thanks, Damian! Fortunately, doing _whatever_ for Perl 6 seems to be mostly a grateful task, AFAICT. -- Jan
Re: Gripes about Pod6 (S26)
On Wednesday 10 February 2010 at 13:49, Patrick R wrote: Actually, it's worth noting that (a slightly modified version of) Perl 5 POD has indeed been used to write several substantial books. I'd be very sad if (Perl 6) POD couldn't be easily used or converted into something that can be used to generate manual pages and reference documentation. I've written and edited several of these books. I'm happy to discuss features and misfeatures and scaffolding I've used to make POD suitable for writing and editing books. Perl 5 POD isn't too far off, but it does lack some important features. For the curious, the Modern Perl Github repository has a book in progress; see the tools/ directory for some hint of the necessary scaffolding: http://github.com/chromatic/modern_perl_book/ (Writing a book isn't too far different from writing documentation; many similar concerns apply.) -- c
Re: Gripes about Pod6 (S26)
On Wed, 10 Feb 2010, Jon Lang wrote: John Gabriele wrote: Personally, I've always thought that Perl has a very natural feel to it, and deserves a doc markup format that's also natural: [Markdown] (and [Pandoc]'s Markdown has just the right additions, IMO). [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ I definitely prefer Markdown's approach to inline markup over POD's approach: e.g., _italic_ strikes me as much more legible than Iitalic. That's one of the things that's always annoyed me with Markdown; I think it should be *bold*, /italic/, and _underline_. :) - | Name: Tim Nelson | Because the Creator is,| | E-mail: wayl...@wayland.id.au| I am | - BEGIN GEEK CODE BLOCK Version 3.12 GCS d+++ s+: a- C++$ U+++$ P+++$ L+++ E- W+ N+ w--- V- PE(+) Y+++ PGP-+++ R(+) !tv b++ DI D G+ e++ h! y- -END GEEK CODE BLOCK-
Re: Gripes about Pod6 (S26)
On Feb 12, 2010, at 19:57 , Timothy S. Nelson wrote: On Wed, 10 Feb 2010, Jon Lang wrote: John Gabriele wrote: Personally, I've always thought that Perl has a very natural feel to it, and deserves a doc markup format that's also natural: [Markdown] (and [Pandoc]'s Markdown has just the right additions, IMO). [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ I definitely prefer Markdown's approach to inline markup over POD's approach: e.g., _italic_ strikes me as much more legible than Iitalic. That's one of the things that's always annoyed me with Markdown; I think it should be *bold*, /italic/, and _underline_. There's a school of thought, common among printing/publishing types, that insists that underline was intended solely to replace italics when they couldn't be represented (i.e. no fonts, as with ASCII terminals and printers). Thus Markdown's use of _italic_. (See also nroff.) -- brandon s. allbery [solaris,freebsd,perl,pugs,haskell] allb...@kf8nh.com system administrator [openafs,heimdal,too many hats] allb...@ece.cmu.edu electrical and computer engineering, carnegie mellon universityKF8NH PGP.sig Description: This is a digitally signed message part
Re: Gripes about Pod6 (S26)
On Fri, 12 Feb 2010, Brandon S. Allbery KF8NH wrote: On Feb 12, 2010, at 19:57 , Timothy S. Nelson wrote: On Wed, 10 Feb 2010, Jon Lang wrote: John Gabriele wrote: Personally, I've always thought that Perl has a very natural feel to it, and deserves a doc markup format that's also natural: [Markdown] (and [Pandoc]'s Markdown has just the right additions, IMO). [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ I definitely prefer Markdown's approach to inline markup over POD's approach: e.g., _italic_ strikes me as much more legible than Iitalic. That's one of the things that's always annoyed me with Markdown; I think it should be *bold*, /italic/, and _underline_. There's a school of thought, common among printing/publishing types, that insists that underline was intended solely to replace italics when they couldn't be represented (i.e. no fonts, as with ASCII terminals and printers). Thus Markdown's use of _italic_. (See also nroff.) I'm aware of that idea, and don't use underlining myself for that reason. But since /italic/ looks like italic, and _underline_ looks like underline, why are we using the thing that looks like underline for italics? I mean, sure, I'm happy to get rid of _underline_ if that's what people want, but using _ for italic is just ... well, I don't see any sense in it. :) - | Name: Tim Nelson | Because the Creator is,| | E-mail: wayl...@wayland.id.au| I am | - BEGIN GEEK CODE BLOCK Version 3.12 GCS d+++ s+: a- C++$ U+++$ P+++$ L+++ E- W+ N+ w--- V- PE(+) Y+++ PGP-+++ R(+) !tv b++ DI D G+ e++ h! y- -END GEEK CODE BLOCK-
Re: Gripes about Pod6 (S26)
On Fri, Feb 12, 2010 at 10:12 PM, Timothy S. Nelson wayl...@wayland.id.auwrote: There's a school of thought, common among printing/publishing types, that insists that underline was intended solely to replace italics when they couldn't be represented (i.e. no fonts, as with ASCII terminals and printers). Thus Markdown's use of _italic_. (See also nroff.) I'm aware of that idea, and don't use underlining myself for that reason. But since /italic/ looks like italic, and _underline_ looks like underline, why are we using the thing that looks like underline for italics? I mean, sure, I'm happy to get rid of _underline_ if that's what people want, but using _ for italic is just ... well, I don't see any sense in it. If I recall correctly, this was a limitation of typewriters. Typewriters were incapable of displaying italics so underlining was taught as a replacement, though italics are/were considered the professional format. I somehow doubt that Markdown chose the _ for italics for that reason, though I will say that wayland's suggestion just makes more sense. -Jason s1n Switzer
