[Pre Wip] Internet based internal-objects html help files that supports translations.

[Lucarda]

This is an example approach to have all help patches from https://github.com/pure-data/pure-data/tree/master/doc/5.reference converted to an easy html. This in turn can simplify translations. (it will take much work to create the initial english htmls) [1].

The translator just copies the source html file and paste it on the corresponding language folder. Then he/she just open the file in a text editor and translates everything inside the html tags <h2>,<p> and <pre>.

Files can live in the pure-data github repo under a special https://pages.github.com/. so this is the server and also the repo for PRs.

Files (for now) can be browsed via https://lucarda.github.io./ . I opted dejavu font just to not decide anything. This of course can be changed. You can test how it renders on the Desktop, tablet or Phone.

demo repo is https://github.com/Lucarda/Lucarda.github.io

---

[1] should be:

• put the title inside a <h2> ... </h2>

• copy the text of each pd comment inside each <p> ... </p> (one comment, one <p>)

• try to do ASCII art of the objects and messages inside a <pre> ... </pre>

No images here as this is no translatable. Just text. If the help patch has sub-patche(s) add like:

<h2>[pd reference]</h2>

<p> walk the cat .. </p>

and so on until all sub patches are covered in the same html file.

[emviveros]

Migrating discution [about graphical context in html doc] (https://github.com/pure-data/pure-data/issues/1320#issuecomment-850869619)

I was proposed a workaround with svg files of help patches with texts manipulated with javascript to aproximate the visual information inside pd help patches.

I don't think it encumbers the effort. You are seen the objects and the connections in the patch while you have web-browser window with the translation at the other side of the screen.

[Lucarda]

it will take much work to create the initial english htmls

Here is a patch that converts a patch to html. it needs improvements but this greatly speeds-up the initial english htmls.

initial-help-patch-2-html.zip

[porres]

let's reference this issue to https://github.com/pure-data/pure-data/issues/1332

[emviveros]

Some questions about the facility for us about using char representation of pd diagrams.

When help patches start to get little messy, like [loop~], or maybe when have lot of input messages like [soundfiler], the char representation of pd diagrams can be problematic for us to write and for readers to?

How we going to deal with subpatches? (in char diagram representation and in svg or images of the help patches)

And the most important (for me) is not a question but a point of view who understands that char representation of diagrams is not a good idea here.

I think my point can be better achieved using the Affordance design concept. Considering our case of representing pd diagrams through chars, what we can say about char affordances is when we see a char, literate people of all ages start to try read words. We can re-signify it and use chars to build images, like ascii art, but it is an enlargement of the properties (affordances) of a char. This way, when we use char pd diagrams, we are creating a new learning demand for the user. It decreases the documentation accessibility in favor of facilities for developers. And I'm still not so sure if they would be really legible in more complicated patches even for those who are already used to it.

I think we can solve it in a better way to complain better accessibility, harmonized with contributions of our community, directly related for this topic in mscotthouston and parallel in: designerfuzzi, in facebook Pd group, pd patch repo forum and pd-list.

[porres]

And the most important in my view is not a question but a point of view who understands that char representation of diagrams is not a good idea here.

agreed

[emviveros]

it will take much work to create the initial english htmls

Here is a patch that converts a patch to html. it needs improvements but this greatly speeds-up the initial english htmls.

initial-help-patch-2-html.zip

Very interesting this concept of generating files in Pd to.. I'm going in paralel way but the same.. How to automate this process which also reminds me that we need to meet the main demand that you raised in my view. How to make life easier for those who will translate the patches.

The idea I can have now is create a workaround which creates files json or xml files (have good documention how to use this files on internet) for the translators. Each translation file generated should have the english text and just below the space to write the text in the translation language. It's the only thing the translator need is the translation json (or whathever) file.

On the other side we need: 1. Generate the translation file in automated way. 2. Create an easy way to implement new languages which brings us to automation again

Regards with 1. we really can do it through Pd Patch because the probability of the translators be pd programmers only is very huge!

Ragard 2. maybe javascript approach can be better because if anyone are interested in upgrade, or modify html doc layout, his chance of knowing how to program in javascript is good, although in this case it is enough to know html and css.. You take the idea.. :P

[Lucarda]

@emviveros i don't seem to understand what you are proposing. translate .pd files? html files? both of them?

About avoiding ascii art:

If we are going to include image files then why not just translate the patch, get a screen-shot, and have an html with just that image file like:

[emviveros]

both of them... But I'm researching about this, and translating SVG files and make it clickable may be time consuming.

Really thinking about your right in translate patch and take a screen-shot. I'm seeing the large of this file is 8 KB. SVG files have the same size.

Do you have suggestions about how to automate the screen-shot task? We will need to make it manually?

[Lucarda]

We will need to make it manually?

yes. also one image for each sub-patch (at least those that need translations).

The main image and the sub-patches images live in the same html.

[emviveros]

But the idea was:

1. parse pd-help files
2. collect all comments
3. tag comments position
4. create translation file like: xml format for ilustration:

   <coments_to_translate>
   <comment_1>
    <en>this is one comment in pd canvas</en>
    <es>este es un comentario en canvas de pd</es>
   </comment_1>
   <comment_2>
    <en>this is another comment in pd canvas</en>
    <es>este es otro comentario en canvas de pd</es>
   </comment_2>
   </coments_to_translate>  

   this way we can maybe with a pd patch generate the translation file to be used in pd translation, or even auto generate patches translated on demand.

[emviveros]

With the translation file we could generate html translations hacking help-patches svg files. And we would use these images in the html references

[emviveros]

In that way, we need to generate the help patch with the comments this is one comment in pd canvas and this is another comment in pd canvas replaced by a mappable string like "comment_1" and "comment_2". This new patch with comments mapped we could generate the svg file, which will be used as base to generate multi languages presentations.

The problem with this workflow is when a comment is breaked in new line, svg file trunc the comment inside diferent tags, each with different parameters of xpos and ypos. And it mess all...

[emviveros]

In an ideal world, if we can do it, is possible download translation packages and generate the help translation files in the user machine. Without need of download all the available language help files in pd world.

about html reference I don't know if is possible to proceed in the same way

[emviveros]

Thinking more, if we can create a translated version of documentation with Pd, we can automate new svg images creation and editing html docs. Or even forget to translate help patches in html pd doc. We can think html pd doc more independent in functionality, avoiding to create patches diagram with comments, since the help patches translated will already be available.

---

[EDIT] one big issue about all these is you will need to review all patches to correct possible text overlays, and documentation stays in someway incompatible with zoom.

[Lucarda]

We can think html pd doc more independent in functionality, avoiding to create patches diagram with comments, since the help patches translated will already be available.

I agree with this. I'm throwing away the idea of ASCII art or SVG.

It would be ok to have some (online only?) html with the content @porres is working on the new "reference" https://github.com/pure-data/pddp/issues/6 section and, maybe, plus some text especially added to the html.

Since the help patches can be translated it could be nice if we find a way to distribute the "translated package" via Deken. Then we can have a way to tell Pd to go and fetch help files in that folder.

I'm uploading here an updated patch2html ( i will put more work to correctly format "commas").

patch2html-v0.1.zip

[umlaeute]

is there a separate issue about "translatable help patches" where i can respond to? (or am i missing something?)

[Lucarda]

is there a separate issue about "translatable help patches" where i can respond to? (or am i missing something?)

@umlaeute see #7

[porres]

how is this going?

[Lucarda]

Seems we don't need the html translatable thing since we can translate the patch.

The infrastructure for this was provided with https://github.com/pure-data/pure-data/pull/1340