I''ve converted all of the inline docs over to restructured text, and I''ve got them all up on trac: http://reductivelabs.com/trac/puppet/wiki/TypeReference http://reductivelabs.com/trac/puppet/wiki/FunctionReference http://reductivelabs.com/trac/puppet/wiki/ReportReference http://reductivelabs.com/trac/puppet/wiki/ConfigurationReference Please let me know if you find any errors in the translation, or in the documents in general. I''ve modified puppetdoc so it can write directly to trac as long as it runs on my server (it uses trac- admin), so it''s very easy to update. I''m 99% of the way to being able to generate all four of these in a single PDF (apparently, it''s around 58 pages), but I''m getting a failure. It worked early on, but I appear to have some kind of unmatched brace in the generated tex. If anyone feels like working on it, you should be able to run ''puppetdoc --all --pdf'' then check / tmp/puppetdoc.log for the failure. -- Death and taxes are inevitable; at least death doesn''t get worse every year. --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
在 24 April , 2007，02:36，Luke Kanies 写道：> I've converted all of the inline docs over to restructured text, and > I've got them all up on trac: > > http://reductivelabs.com/trac/puppet/wiki/TypeReference > http://reductivelabs.com/trac/puppet/wiki/FunctionReference > http://reductivelabs.com/trac/puppet/wiki/ReportReference > http://reductivelabs.com/trac/puppet/wiki/ConfigurationReference > > Please let me know if you find any errors in the translation, or in > the documents in general. I've modified puppetdoc so it can write > directly to trac as long as it runs on my server (it uses trac- > admin), so it's very easy to update.It's great to have these up. Maybe we move the ToC to the end of the document and add an <h1> with the page title at the beginning? _______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users
On Apr 24, 2007, at 7:19 AM, Benjamin C. Kite wrote:> > It''s great to have these up. > > Maybe we move the ToC to the end of the document and add an <h1> with > the page title at the beginning?ToC at the end, huh? Is this common practice? What do people think about splitting the Type reference into separate pages, one per type? I''m autogenerating all of the pages using trac-admin, so it''s basically free to do so. -- Now and then an innocent man is sent to the legislature. --Kin Hubbard --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
I''d say to keep the TOC at the top but only go three levels deep, instead of four as it is now. I also prefer one page for scrollability. Trevor On 4/24/07, Luke Kanies <luke@madstop.com> wrote:> > On Apr 24, 2007, at 7:19 AM, Benjamin C. Kite wrote: > > > > It''s great to have these up. > > > > Maybe we move the ToC to the end of the document and add an <h1> with > > the page title at the beginning? > > ToC at the end, huh? Is this common practice? > > What do people think about splitting the Type reference into separate > pages, one per type? > > I''m autogenerating all of the pages using trac-admin, so it''s > basically free to do so. > > -- > Now and then an innocent man is sent to the legislature. > --Kin Hubbard > --------------------------------------------------------------------- > Luke Kanies | http://reductivelabs.com | http://madstop.com > > > _______________________________________________ > Puppet-users mailing list > Puppet-users@madstop.com > https://mail.madstop.com/mailman/listinfo/puppet-users >_______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users
在 24 April , 2007，12:45，Luke Kanies 写道：> ToC at the end, huh? Is this common practice?This ToC ends up looking a lot more like an index, I think. Maybe if it looked more like a ToC or had more information on each entry. Not sure, just my gut instinct.> > What do people think about splitting the Type reference into separate > pages, one per type?I say one-per-type, especially if we're considering annotations like the PHP website has.> I'm autogenerating all of the pages using trac-admin, so it's > basically free to do so._______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users
On Apr 24, 2007, at 11:54 AM, Trevor Vaughan wrote:> I''d say to keep the TOC at the top but only go three levels deep, > instead of four as it is now.Done: http://reductivelabs.com/trac/puppet/wiki/TypeReference I had to refactor puppetdoc to support per-page depth settings, but it was necessary anyway, since I hadn''t refactored it since its initial development.> I also prefer one page for scrollability.Anyone else care one way or another? Is anyone particularly keen on a PDF of all of the reference materials? -- I never think of the future. It comes soon enough. --Albert Einstein --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
On Apr 24, 2007, at 10:52 AM, Benjamin C. Kite wrote:> > 在 24 April , 2007，12:45，Luke Kanies 写道： > >> ToC at the end, huh? Is this common practice? > > This ToC ends up looking a lot more like an index, I think. Maybe > if it looked more like a ToC or had more information on each entry. > Not sure, just my gut instinct. > >> >> What do people think about splitting the Type reference into separate >> pages, one per type? > > I say one-per-type, especially if we're considering annotations like > the PHP website has.Won't some of these be far more than a single page? Unless you're just talking about the wiki.. in which case I totally agree. I think it'd also be cool to have a wiki page dedicated to parameters that are similar for all types but may have differences that need to be obvious. Like ensure, etc. -Blake _______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users
On Apr 24, 2007, at 2:12 PM, Blake Barnett wrote:> > Won''t some of these be far more than a single page? Unless you''re > just talking about the wiki.. in which case I totally agree. I think > it''d also be cool to have a wiki page dedicated to parameters that > are similar for all types but may have differences that need to be > obvious. Like ensure, etc.For ''single page'', I meant one page per type, rather than having all types on one page, and I was just talking about the wiki. I don''t really know what you mean about that parameter documentation, but I''m specifically referring to the autogenerated references here, which are all pulled from code and turned into these RST documents. You should be able to run puppetdoc yourself (e.g., ''puppetdoc -s type | less'') to get an idea of the output. Ben brought up the idea of doing it like some other sites do, where we generate all of them -- a separate page for every type, plus all of them together, plus the whole reference in one page -- which I think is a good idea but is a bit more than I''m planning on biting off right now. If you have comments or requests on the reference docs, let me know; at this point I''m going to switch back to other work. -- Measure with a micrometer. Mark with chalk. Cut with an axe. --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
> ToC at the end, huh? Is this common practice? > > What do people think about splitting the Type reference into separate > pages, one per type? > > I''m autogenerating all of the pages using trac-admin, so it''s > basically free to do so. > > -- >i think this could be good or it should have a type name bigger than the type params so we ca easily find it. Right now i find it a little hard to go from type to type on the page. -- Cordialement, Ghislain _______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users
On Apr 25, 2007, at 2:07 AM, ADNET Ghislain wrote:> i think this could be good or it should have a type name bigger > than the type params so we ca easily find it. Right now i find it a > little hard to go from type to type on the page.This should be fixed now. -- Don''t throw away the old bucket until you know whether the new one holds water. -- Swedish Proverb --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
Luke Kanies a écrit :> On Apr 25, 2007, at 2:07 AM, ADNET Ghislain wrote: > >> i think this could be good or it should have a type name bigger >> than the type params so we ca easily find it. Right now i find it a >> little hard to go from type to type on the page. >> > > This should be fixed now. > >yes i noticed, it is very readable now , thanks Luke ! -- Cordialement, Ghislain _______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users