search

gbif / doc-openrefine-guide

Guía de Uso Básico de OpenRefine para la limpieza de datos sobre biodiversidad
https://doi.org/10.15468/doc-gzjg-af18
Other
2 stars 2 forks source link

Styling question: green text #3

Closed kcopas closed 4 years ago

kcopas commented 5 years ago

@pzermoglio and @tucotuco —

Can you explain more regarding your intention with the green text formatting that's described thus:

En el texto, los nombres de los campos originales se marcan con color verde claro.

Not saying we can't do this, but I'd prefer for us to have a consistent way of styling and formatting text across all docs. I just need to understand how it's different, say, from NOTA and IMPORTANTE.

kcopas commented 5 years ago

lostintranslation is probably most appropriate here...

pzermoglio commented 5 years ago

@kcopas ha! Yes, these are the reasons for it not being equal to a note:

The EN translation of that text would be: "In the text, the names of the original fields are marked in light green".

In the guide, this is used for example when more or less complex and/or long grel expressions are explained to the reader, that act on particular fields (eg, an expression working on the fields genus and specificEpithet) so that it is clearer for the reader which is the field, which is the function, and so on. As there is light green used for field names, there are also other colors used in those expressions throughout the whole guide (e.g., "if"s are put in blue).

Right now none of this shows in what is rendered as html or pdf from the adoc, but it should look like eg this expression (top of page 16): image

This is one of the reasons why I think it is necessary for authors to understand how to communicate this format requirements when they submit their documents, as it really makes a difference regarding the quality and usability of the document for the users if these format styling from the authors is respected...

kcopas commented 5 years ago

it is necessary for authors to understand how to communicate this format requirements when they submit their documents

Absolutely, thanks. The Word and PDF versions are very useful in that regard—they signal to us (me) that there are some specific formatting requirements needed here, and here, and...

None of these elements are styled consistently yet, though I have started testing out a few techniques.

Do you see these colour conventions as being anything like standard or consistent across the software documentation that you know? I'm going to have a look at some O'Reilly books to see how they render these. If you view any as particularly helpful or relevant precedents, do share, please.

MattBlissett commented 5 years ago

"In the text, the names of the original fields are marked in light green"

I would rephrase that as "…are marked like this" (just using a style I can do in a Github comment) so the document still makes sense if printed in black and white.

Since this is Javascript, the built-in syntax highlighting would get something like

if(isBlank(cells["genus"].value), "", cells["genus"].value) + " " +
  if(isBlank(cells["specificEpithet"].value), "", cells["specificEpithet"].value)

This is marked up like this in Asciidoctor:

[source,javascript]
----
if(isBlank(cells["genus"].value)…
----

but only works for a whole block.

I will investigate

Puede llamar al nuevo campo “concat_scientificName”, para indicar que se trata de la concatenación (note que ya hay un campo scientificName en los datos).

I think this would become

Puede llamar al nuevo campo `concat_scientificName`, para indicar que se trata
de la concatenación (note que ya hay un campo [.field]`scientificName` en los datos).

And for the rainbow:
[.field.custom1]`coordinate`
[.field.custom2]`date`
[.field.custom3]`locality`
pzermoglio commented 5 years ago

Do you see these colour conventions as being anything like standard or consistent across the software documentation that you know?

Nop, I do not know of any particular convention... It would seem from what I could find that syntax highlighting is recommended all over but the choice of colors is up to the user, same in semantic highlighting (see eg semanticolor).

I would rephrase that as "…are marked like this" (just using a style I can do in a Github comment) so the document still makes sense if printed in black and white.

I think I see the issue here, how to deal with black and white... but I can't come up with a good solution, combination of bold, italic, etc would not cover enough, imo.

what to do with the rainbow of highlighting in the JSON on page 49 (!).

yeah, I know! But believe me the guide has gone through use by a lot of people in several online and onsite courses and it does make a difference to have the rainbow for those who've never encountered json before. Would be great if rainbows could be better defined, though, including which palettes to use.

kcopas commented 5 years ago

There are conventions within AsciiDoc that Matt is looking to tap into.

MattBlissett commented 5 years ago

semantic highlighting

That's an interesting concept, and a good demonstration of why this is helpful. I haven't investigated if it can be integrated into AsciiDoctor.

I've extended AsciiDoctor to do inline syntax highlighting, so 

some.javascript("code")

would look the same as some.javascript("code").

I've also gone through the document Kyle has already converted to AsciiDoctor, applied this syntax, and added the next section to Chapter 4, to show the other way of highlighting parts of the code, with Callouts.

I hope that's enough to proceed.

I will look at the out-of-context highlighting later in May.

kcopas commented 5 years ago

I hope that the styling we've introduced mirrors your intent, @pzermoglio.

Piggybacking a related item on this issue since it's still open: in Line 17 of the intro/preface, you write:

En el texto, los https://github.com/gbif/doc-openrefine-guide/blob/master/preface.es.adoc#cómo-usar-esta-gu%C3%ADa[*nombre de los campos originales*] se marcan con color verde claro.

I think that our adaptation requires restating this slightly to say that. the fields 'are marked as code' or some such. Just flagging it now, as I finally dig into a full read-through against your print draft.

kcopas commented 5 years ago

Proposed change in line above:

En el texto, los nombre de los campos originales se marcan como código.

@MattBlissett can you have a look at your unchecked tasks above?

I propose we wrap up this issue in the coming week, if possible…

pzermoglio commented 5 years ago

Revisiting this issue, and reviewing the whole guide, I find the following standing problems:

@kcopas In the text, as it stands now, with the fields written "as code" some fields that are not original fields are marked "as code" (eg, field [source] "Todo"; original fields are here dwc fields used in the data provided). I think distinguishing the original fields was something useful, but looking at it again, we could just leave all highlighted as code as it stands now. Maybe after community input we can tell if the coloring was really necessary and if so try something else. I'll wait for your thumbs up to take the phrase out of the text.

It does! @MattBlissett 's solutions look good. Yet, there are a couple of things that I noted:

MattBlissett commented 5 years ago

Revisiting this issue, and reviewing the whole guide, I find the following standing problems:

Proposed change in line above: En el texto, los nombre de los campos originales se marcan como código.

@kcopas In the text, as it stands now, with the fields written "as code" some fields that are not original fields are marked "as code" (eg, field [source] "Todo"; original fields are here dwc fields used in the data provided). I think distinguishing the original fields was something useful, but looking at it again, we could just leave all highlighted as code as it stands now. Maybe after community input we can tell if the coloring was really necessary and if so try something else. I'll wait for your thumbs up to take the phrase out of the text.

  1. I hadn't realized that "todo" is Spanish for "all" ("all columns"), so it's appropriate to remove the code highlighting for this word. I've done this.

  2. I like the idea of semantic highlighting, and I can see the benefit here, but it's unusual — Kyle won't find it in any O'Reilly guides! It's not supported by default by AsciiDoctor or any other document markup system we reviewed.

    At the moment, all Javascript strings are highlighted in red, for example the URL in §4.1.1 is part of a Javascript expression.

    It would be possible to add support for custom highlighting to AsciiDoctor, though I don't think this is easy if it builds on the existing syntax highlighting. Removing the built-in Javascript highlighting, and adding a custom markup character, could mean this:

    ...escape(cells["¤scientificName¤"].value, "url")

    was all monospaced text, with scientificName coloured. Let's see what the community think.

The format works fine in the html version, but it gets distorted in the pdf version. Eg: section 2.1.3: html: image pdf: image Anything that could be done for both versions to match each other better?

I have made an issue for this: https://github.com/gbif/gbif-asciidoctor-toolkit/issues/2

Some coloring is a bit weird in the sense of it does not reflect things we want to point out for the reader. Eg: section 4.1.1: image For instance, the reader does not really want to be pointed out that results are being pulled from 'data' and 'results' arrangements. (in this case, pdf version does seem to mirror html rendering, though different colors; not sure why this one would work when others don't...). Same eg Section 4.1.2, The cases (casos) do not highlight what we want to highlight… Eg: image (should look sth like: image What’s important there is that there are no results. I fear that highlighting so many other things, the important part for the -non-expert- reader might be lost... Any insights on this would be good. (@kcopas @MattBlissett @tucotuco)

This is the "normal" vs semantic highlighting, as above.

I really like how, in section 4.1.1, case 2 is shown with the circled numbers. Yet the others are not totally consistent. Case 1 (example just above) does not point to the important part. Case 3: Numbers need to be re-numbered, as they do not match numbers described for case 1. This is because in the original coloring each color represented a kind of element, rather than the order in which the elements appear (eg, turquoise was the |:Adm -administrative division, no matter if it appeared in first, second or last place, always same color. Now it has numbers 6 in Case 2, but 4 in Case 3).

[ ] Making this a TO DO for myself. I take it that is can be easily changed replacing the '(1)' for whatever number, but will need to add brief text to it. Will try this modifications.

Yes, it should be easy to move around the numbers, and maybe add a number to the "numResults" line for case 1. The numbers were the best built-in feature of AsciiDoctor which I could use instead of semantic highlighting.

I've made a pull request to show one way of changing the forEach expression to use numbers: #12.

kcopas commented 5 years ago

I'll wait for your thumbs up to take the phrase out of the text.

Yes, please—I didn't think for a moment el gringo viejo would get it right, but I did hope that getting it at least somewhat wrong would prompt the fix.