I’m suggesting that both website docs AND local docs opened in/by Pd can be the same html+media.
-------- Dan Wilcox @danomatika <https://twitter.com/danomatika> danomatika.com <http://danomatika.com/> robotcowboy.com <http://robotcowboy.com/> > On Feb 26, 2016, at 6:09 PM, Lucas Cordiviola <lucard...@hotmail.com> wrote: > > Can it be done with puredata.info <http://puredata.info/>? > > Mensaje telepatico asistido por maquinas. > > From: danomat...@gmail.com > Date: Fri, 26 Feb 2016 17:35:58 -0700 > To: jancs...@yahoo.com > CC: pd-list@lists.iem.at > Subject: Re: [PD] multi-language help patches > > I'd look at how the processing team has put their site/reference together: > https://github.com/processing/processing-docs > <https://github.com/processing/processing-docs> > > It's basically using a php engine with content written and parsed in xml. > Each function/class to be documented has it's own file and each file starts > form a template which the author then just needs to fill out. I'm not > suggesting using xml, etc but I like the layout from an editing & parsing > perspective. > > And this is the processing reference, which I feel is a great model for a > teaching/arts environment (aka good balance towards readability for beginners > and the important info for pros). This section is also included when you > download Processing and opened automatically via a link form the Processing > IDE itself as well as contextual menu when hilghighting functions & classes > in the editor: > > https://processing.org/reference/ <https://processing.org/reference/> > > Openframeworks has been going in that direction, but the codebase is a lot > larger and the underlying C++ requires more details to explain, etc hence the > recent DocSprint. So far, the examples have been refreshed and lots of useful > snippets & longer form tutorials/books have been put together: > > New Learning page from last weekend: http://openframeworks.cc/learning/ > <http://openframeworks.cc/learning/> > Existing reference: http://openframeworks.cc/documentation/ > <http://openframeworks.cc/documentation/> > > Here's the current OF website using markdown parsing & generation: > https://github.com/openframeworks/ofSite > <https://github.com/openframeworks/ofSite> > > And here's a new approach to generating the OF documentation as a work in > progress: > https://github.com/halfdanj/ofdocumentationgenerator > <https://github.com/halfdanj/ofdocumentationgenerator> > > Here's a couple docs and workflows that have come out of and/or been > generated by the DocSprint work: > > https://hackpad.com/API-Documentation-Overview-wCQ4J5hrBbW > <https://hackpad.com/API-Documentation-Overview-wCQ4J5hrBbW> > > https://github.com/openframeworks/openFrameworks/wiki/Examples-Contribution-Process-Flow > > <https://github.com/openframeworks/openFrameworks/wiki/Examples-Contribution-Process-Flow> > > I feel one of the best aspects of PD are the examples via help patches so > maybe splitting things up outside of PD might work against that? However, > this would allow for a place for larger scale information as well as images, > embed, etc. > > -------- > Dan Wilcox > @danomatika <https://twitter.com/danomatika> > danomatika.com <http://danomatika.com/> > robotcowboy.com <http://robotcowboy.com/> > On Feb 26, 2016, at 5:20 PM, Jonathan Wilkes <jancs...@yahoo.com > <mailto:jancs...@yahoo.com>> wrote: > > Do you have a spec from that sprint? > > > On Friday, February 26, 2016 7:08 PM, Dan Wilcox <danomat...@gmail.com > <mailto:danomat...@gmail.com>> wrote: > > > Also, my thinking is going in this direction as we’re dealing with the same > issues in the OpenFrameworks community. My uni department just hosted an OF > DocSprint last weekend and we spent a good amount of time wrangling how best > to integrate a Markdown + Doxygen generated reference system. > > Of course pure data patch files and C++ source files are somewhat different, > but I feel there are the same issues to solve such as what requires the most > maintenance, works on all platforms, and is easy for non developer > contributors to use. It’s one thing to build a custom system (we did) and > quite another to get people to pitch in and fill the content in. I just > wouldn’t want anyone to spend a lot of time making something admittedly cool > and built into the canvas but, in the end, may not be leveraged by the > community the same way a portable, easy to edit, cross platform standard > might. > > -------- > Dan Wilcox > @danomatika <https://twitter.com/danomatika> > danomatika.com <http://danomatika.com/> > robotcowboy.com <http://robotcowboy.com/> > On Feb 26, 2016, at 5:01 PM, Dan Wilcox <danomat...@gmail.com > <mailto:danomat...@gmail.com>> wrote: > > > Ok, so which html reference system should I leverage here? > > Probably something using css and an html template that make it easy for > people to fill out. I’d say 1 main html file for each object to document w/ > room for sub pages if needed. Different languages can live in different > folders. > > The nice thing about this approach is lots of people can edit html, there are > plenty of designers, the files can be rendered by pretty much anything, etc. > Another option is to have a templating system that uses Markdown, etc and > just renders to html. It can then live in it’s own source repository for > shared work and be used as a basis for online as well as distributed > documentation. > > Maybe a good start would be to look at the pure data object database/wiki > that is around somewhere. I can’t find the link off the top of my head. > > Where will > the html files get stored, and how do we get from clicking the link in the > help patch (I'm assuming we're still using the current help patches to show > a simple demo of the object) to opening the html doc in the correct language? > > Just like opening a help patch with a context menu option or maybe links we > can open from the patch itself. Use the current help paths for searching and > use tcl to launch the path in the system web browser if found. > > I’d say the most useful thing would be add linking between patches and > external files (html, etc) in general. I believe Hans had this in extended > for the pd-doc stuff. > > I’m suggesting this approach partially so you/we don’t end up reinventing the > wheel. A custom, integrated system would be *nice* but I feel that will > require too much backend work to build and them probably too much work to > maintain/extend in the future. HTML+CSS has the option of being loaded into a > web view within TK I imagine, so another option would be a side pane or extra > window that can open up right in PD. I’d suggest staying away from building > extra widgets etc to render a custom approach within the patch itself. > > -------- > Dan Wilcox > @danomatika <https://twitter.com/danomatika> > danomatika.com <http://danomatika.com/> > robotcowboy.com <http://robotcowboy.com/> > On Feb 26, 2016, at 4:44 PM, Jonathan Wilkes <jancs...@yahoo.com > <mailto:jancs...@yahoo.com>> wrote: > > > -Jonathan > > > On Friday, February 26, 2016 4:34 PM, Dan Wilcox <danomat...@gmail.com > <mailto:danomat...@gmail.com>> wrote: > > > I think what implying is that maybe Pd *doesn’t* need to handle it. Simply, > Pd could open a local webpage, similar to how the Processing “Find in > reference” context menu option works when highlighting a function in the > editor. > > Not to say you/we can’t work out a file format/system to handle alot of this, > but I’m thinking that html reference already works well for many other > contexts an doesn’t require building new formats/systems to solve alot of the > same problems. > > -------- > Dan Wilcox > @danomatika <https:/> > danomatika.com <https:/> > robotcowboy.com <https:/> > On Feb 26, 2016, at 2:08 PM, Jonathan Wilkes <jancs...@yahoo.com <https:/>> > wrote: > > html could be leveraged, but I'm really looking for a spec for how Pd > handles it. Is it a GUI widget? An abstraction? A canvas method? A new > "#" directive? > > Do the translations get saved along with the help patch, or are they stored > in > a directory and fetched when needed? Etc. > > -Jonathan > > > On Friday, February 26, 2016 1:02 PM, Dan Wilcox <danomat...@gmail.com > <https:/>> wrote: > > > I'll implement any *clear* spec for multi-language help patches someone comes > up > with with the following constraints: > 1. it separates design from content. > 2. in only requires documentation writers to care about content. > 3. it does not pigeonhole help patches into having a single, ugly design > 4. documentation writers will be guaranteed that whatever they write, it > won't > overlap patch content. > 5. it is maintainable and scalable > > Sounds like .html. > > -------- > Dan Wilcox > @danomatika <https:/> > danomatika.com <https:/> > robotcowboy.com <https:/> > > _______________________________________________ > Pd-list@lists.iem.at <https:/> mailing list > UNSUBSCRIBE and account-management -> > http://lists.puredata.info/listinfo/pd-list <https:/> > > > > > > > > > > > > _______________________________________________ Pd-list@lists.iem.at > <mailto:Pd-list@lists.iem.at> mailing list UNSUBSCRIBE and account-management > -> http://lists.puredata.info/listinfo/pd-list > <http://lists.puredata.info/listinfo/pd-list>
_______________________________________________ Pd-list@lists.iem.at mailing list UNSUBSCRIBE and account-management -> http://lists.puredata.info/listinfo/pd-list
