[L2Ork-dev] Help doc improvement

[Jonathan Wilkes]

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