Keith, I love the new cleaned up look, it is much more readable and professional.
I agree with Doug that $subsections makes sense and hopefully you'll able to convert all the docs files semi-automatically using regular expressions. As for the missing prev/next links, these are computed from the $subsection elements; perhaps the reason they disappeared is because you should change the code to understand $subsections too. Slava On Wed, Sep 16, 2009 at 11:48 AM, Keith Lazuka <[email protected]> wrote: > Hi all, > > I'm working on cleaning up Factor's built-in help articles. I wrote a > little blog post summarizing my progress and to get some feedback: > http://klazuka.tumblr.com/post/189527736/factor-help-articles-cleanup > > One thing I'm not sure about is whether it's worth the trouble to > introduce new markup, especially since I will need to make changes > throughout hundreds of *-docs.factor files. If we do use the new > markup, it will make it easier down the road to change the styling of > these word groups. If we don't, then I will still need to manually > insert explicit newline markup between each word group throughout > several hundred *-docs.factor files in order to get the right spacing > between the groups. > > Another concern is whether my new markup syntax jives with Factor's > existing markup. > > Here is an example of the old markup: > ARTICLE: "sequences-combinators" "Sequence combinators" > "Iteration:" > { $subsection each } > { $subsection each-index } > { $subsection reduce } > { $subsection interleave } > { $subsection replicate } > { $subsection replicate-as } > "Mapping:" > { $subsection map } > { $subsection map-as } > { $subsection map-index } > { $subsection map-reduce } > { $subsection accumulate } > { $subsection produce } > { $subsection produce-as } > "Filtering:" > { $subsection filter } > { $subsection partition } > "Testing if a sequence contains elements satisfying a predicate:" > { $subsection any? } > { $subsection all? } > { $subsection "sequence-2combinators" } > { $subsection "sequence-3combinators" } ; > > ------------ > > And the new markup: > ARTICLE: "sequences-combinators" "Sequence combinators" > { $group "Iteration:" > each > each-index > reduce > interleave > replicate > replicate-as > } > { $group "Mapping:" > map > map-as > map-index > map-reduce > accumulate > produce > produce-as > } > { $group "Filtering:" > filter > partition > } > { $group "Testing if a sequence contains elements satisfying a predicate:" > any? > all? > } > { $heading "Related Articles" } > { $subsection "sequence-2combinators" } > { $subsection "sequence-3combinators" } ; > > -------------------------------------------------------------------- > > Any thoughts? > > -keith > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry® Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9-12, 2009. Register now! > http://p.sf.net/sfu/devconf > _______________________________________________ > Factor-talk mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/factor-talk > ------------------------------------------------------------------------------ Come build with us! The BlackBerry® Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9-12, 2009. Register now! http://p.sf.net/sfu/devconf _______________________________________________ Factor-talk mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/factor-talk
