[L2Ork-dev] Help doc improvement

Mon Mar 1 08:02:21 EST 2021

PD META approach is what 1.0 and K12 supports and is cleaner, as many nlet
(nlet=inlet(~) or outlet(~)) descriptions will require more than a word to
describe its function. This will make nlet objects long and unwieldy and
difficult to handle any potential future additions of arguments. Besides,
most of the help patches already have the Meta subpatch, making it useful
not only for abstractions, but also for actual objects. Lastly, the current
lack of Meta tooltip support breaks backwards compatibility.

Best,

Ico

-- 
Ivica Ico Bukvic, D.M.A.
Director, Creativity + Innovation
Institute for Creativity, Arts, and Technology

Virginia Tech
Creative Technologies in Music
School of Performing Arts – 0141
Blacksburg, VA 24061
(540) 231-6139
ico at vt.edu

www.icat.vt.edu
www.performingarts.vt.edu
l2ork.icat.vt.edu
ico.bukvic.net

On Sat, Feb 27, 2021, 14:01 Jonathan Wilkes <jon.w.wilkes at gmail.com> wrote:

> On Sat, Feb 27, 2021 at 7:30 AM Flachy Joe <flachyjoe at gmail.com> wrote:
> >
> > Another possibility could be to use text comments for the tooltips.
> > Every text above (under) inlets(outlets) comments them in the same order.
>
> I think using inlet(~)/outlet(~) arguments is cleaner. Still, these
> approaches don't
> cover the common case of having a tooltip for the abstraction itself.
> Mousing over the
> inlet 0 we may want "frequency" to be displayed. But mousing over the
> object box
> itself we may want "bandlimited saw wave".
>
> Original approach was to put comments in a [pd META] subpatch of the help
> patch,
> and then parse that when the user hovered over a box or an xlet. But
> that's a pain
> to maintain, e.g., the help patch author writes a normal description
> in the main patch,
> then has to re-write it in the [pd META] subpatch, plus keep them sync'd.
>
> -Jonathan
>
> >
> > Le 25/02/2021 à 21:40, Jonathan Wilkes a écrit :
> > > On Thu, Feb 25, 2021 at 2:49 PM Flachy Joe <flachyjoe at gmail.com>
> wrote:
> > >> Hi,
> > >>
> > >> in the same way, can inlet/outlet be tooltiped ?
> > >>
> > >> I think about an argument to inlet which be shown in parent when
> mouse is on the small rectangle. Symbol args are already allowed for inlet
> but ignored so this improvement will be backcompatible.
> > > But it is not ignored for inlet~/outlet~ where it is used for
> up/downsampling.
> > >
> > > Also-- in the comments of the code for xlets, a future possibility
> > > mentions using indices if more up/downsampling options are added. So
> > > while `[inlet~ hold 2nd argument begins the tooltip]` would currently
> > > work, we don't know if there are plans for using that 2nd argument
> > > that would break patches.
> > >
> > > If Miller's plan is to only ever use the first argument, then I
> > > suppose we could use a dash "-" to do something like [inlet~ - tooltip
> > > goes here]. It's not great, but it's already a precedent with
> > > [get]/[set]
> > >
> > > -Jonathan
> > >
> > >> Regards,
> > >> FF
> > >>
> > >> Le 25/02/2021 à 19:33, Albert Graef a écrit :
> > >>
> > >> Hi Jonathan,
> > >>
> > >> that sounds like an awesome idea to me! Have you already implemented
> this? I'm really looking forward to giving it a whirl.
> > >>
> > >> Thanks,
> > >> Albert
> > >>
> > >>
> > >> On Tue, Feb 23, 2021 at 12:35 AM Jonathan Wilkes <
> jon.w.wilkes at gmail.com> wrote:
> > >>> Hi all,
> > >>>
> > >>> Just had a documentation epiphany:
> > >>>
> > >>> 1. add a div above the svg for a canvas (for now just assume every
> > >>> canvas window has such a div)
> > >>>
> > >>> 2. add an offset for checking mouse coords that subtracts the bottom
> > >>> of this div from the pageY
> > >>>
> > >>> 3. have the GUI check if a new canvas to be created has "-help.pd" in
> > >>> the title. E.g., "float-help.pd"
> > >>>
> > >>> 2. If so, flag it and stat "float.md"
> > >>>
> > >>> 3. If "float.md" exists, grab the contents, parse them with a
> markdown
> > >>> parser, and shove it all into the div's innerHTML from step 1.
> > >>>
> > >>> 4. Now we have a uniform help system where it's easy to write free
> > >>> prose, and it will wrap responsively when resizing the window, with
> an
> > >>> example patch at the bottom.
> > >>>
> > >>> 5. can easily add "float_de.md" and "float_fr.md" for multi-language
> help.
> > >>>
> > >>> This will make the core help docs *way* easier to edit, track in git,
> > >>> and read. And it shouldn't be *too* hard to convert the current mess
> > >>> of comments and cnv labels to markdown files to get started.
> > >>>
> > >>> As a side-benefit, we can also search for "patchname-help.html" and
> if
> > >>> it exists, load it up in the div's innerHTML. That will give people a
> > >>> way to write arbitrary html stuff to be displayed and used in
> > >>> conjunction the "patchname-help.pd" patch.
> > >>>
> > >>> If it works we can look later about how to edit the markdown in
> > >>> editmode, how to display/hide the example patch, etc.
> > >>>
> > >>> Best,
> > >>> Jonathan
> > >>> _______________________________________________
> > >>> L2Ork-dev mailing list
> > >>> L2Ork-dev at disis.music.vt.edu
> > >>> https://disis.music.vt.edu/listinfo/l2ork-dev
> > >>
> > >>
> > >> --
> > >> Dr. Albert Gr"af
> > >> Computer Music Research Group, JGU Mainz, Germany
> > >> Email: aggraef at gmail.com, web: https://agraef.github.io/
> > >>
> > >> _______________________________________________
> > >> L2Ork-dev mailing list
> > >> L2Ork-dev at disis.music.vt.edu
> > >> https://disis.music.vt.edu/listinfo/l2ork-dev
> > >>
> > >> _______________________________________________
> > >> L2Ork-dev mailing list
> > >> L2Ork-dev at disis.music.vt.edu
> > >> https://disis.music.vt.edu/listinfo/l2ork-dev
> > > _______________________________________________
> > > L2Ork-dev mailing list
> > > L2Ork-dev at disis.music.vt.edu
> > > https://disis.music.vt.edu/listinfo/l2ork-dev
> > _______________________________________________
> > L2Ork-dev mailing list
> > L2Ork-dev at disis.music.vt.edu
> > https://disis.music.vt.edu/listinfo/l2ork-dev
> _______________________________________________
> L2Ork-dev mailing list
> L2Ork-dev at disis.music.vt.edu
> https://disis.music.vt.edu/listinfo/l2ork-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://disis.music.vt.edu/pipermail/l2ork-dev/attachments/20210301/514e756e/attachment-0001.html>