Style/content items from read-through

[kcopas]

Recording what seems to me to be the remaining issues to address before circulating this for review (leaving aside all that needs to be prepared to make that straightforward for reviewers):

• [ ] Consistent styling for menu commands: I don't feel like I have a handle on how we should represent commands like 'File > Open as...'. What makes it even harder are the places where these are called out in a separate line. Should we style them in code-like fashion? Try to find a simple block indent (need your help in parsing the AsciiDoctor user manual for that @MattBlissett)?
• [ ] Consistent styling of steps and examples. I'd like to propose using the same '[discrete]' block style for the cases and métodos in §4.1.2 that I applied to the steps in §1. I wanted to ask about this first, though—not least because the former contains the code that @MattBlissett restyled into more a more structured view. I don't want to blow it up, but I also don't want to propose changes to something that @pzermoglio and @tucotuco might not yet have approved.

A couple other smaller scale items coming as separate and easily resolvable issues...

[MattBlissett]

1. Menus:

There is an experimental menu syntax which I have activated: https://github.com/gbif/doc-openrefine-guide/commit/4f4a8a441833c610a4a19db7f16ab03a5bf69330

It's not fully documented, the syntax "File > Save as…" is also available (quotes and > signs).

I've also used "la ▼ azul" instead of "la flecha azul" (a simple search-replace can undo this bit if needed).

That done, it doesn't really show up very well in the rendered document. I think it would be better with a sans-serif font, or a faint outline, or something like that.

I slightly reworded the place where there are several submenu options.

[pzermoglio]

@MattBlissett I like "la ▼ azul" instead of "la flecha azul" ! I've found, however, that in some places it appears within quotes and in some others it does not... Eg Section 2.1.3: Click en "la ▼ azul del campo genus > Editar columnas > Agregar columna basada en esta columna…" Section 2.2.3: Para ello, hacer click en la ▼ azul del campo y seguir la ruta:

I explored both cases but they look just the same to me in the adoc, I could not figure why it would be rendering them differently...

[MattBlissett]

The difference is just normal quote marks within the AsciiDoc source:

https://github.com/gbif/doc-openrefine-guide/blob/d7109d8108d3324b2a9041a2e22b50054177e1bf/ch02.es.adoc#L82-L84

https://github.com/gbif/doc-openrefine-guide/blob/d7109d8108d3324b2a9041a2e22b50054177e1bf/ch02b.es.adoc#L72-L74

[tucotuco]

Hi folks,

I am curious whether the intention is to achieve consistency just within the OpenRefine document, or to try to set expectations about style for all documents. I worry a bit if it is the latter and just wanted to ask.

Cheers,

John

On Wed, May 1, 2019 at 5:43 AM Kyle Copas notifications@github.com wrote:

Recording what seems to me to be the remaining issues to address before circulating this for review (leaving aside all that needs to be prepared to make that straightforward for reviewers):

• [ ] Consistent styling for menu commands: I don't feel like I have a handle on how we should represent commands like 'File > Open as...'. What makes it even harder are the places where these are called out in a separate line. Should we style them in code-like fashion? Try to find a simple block indent (need your help in parsing the AsciiDoctor user manual for that @MattBlissett https://github.com/MattBlissett)?
• [ ] Consistent styling of steps and examples. I'd like to propose using the same '[discrete]' block style for the cases and métodos in § 4.1.2 https://labs.gbif.org/documents/openrefine-guide/es/#_georreferenciaci%C3%B3n_usando_geolocate that I applied to the steps in §1 https://labs.gbif.org/documents/openrefine-guide/es/#_carga_de_datos_y_creaci%C3%B3n_de_un_proyecto. I wanted to ask about this first, though—not least because the former contains the code that @MattBlissett https://github.com/MattBlissett restyled into more a more structured view. I don't want to blow it up, but I also don't want to propose changes to something that @pzermoglio https://github.com/pzermoglio and @tucotuco https://github.com/tucotuco might not yet have approved.

A couple other smaller scale items coming as separate and easily resolvable issues...

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/gbif/doc-openrefine-guide/issues/5, or mute the thread https://github.com/notifications/unsubscribe-auth/AADQ723D2WF4NIKV5GXEDOTPTFJ2XANCNFSM4HJSMSQQ .

[kcopas]

I think it's safe to say that we're thinking about both the present example and the general case.

[MattBlissett]

Section 2.1.3: Click en "la ▼ azul del campo genus > Editar columnas > Agregar columna basada en esta columna…" Section 2.2.3: Para ello, hacer click en la ▼ azul del campo y seguir la ruta:

I've realized what you meant, I misunderstood last year (!). When the menu item itself included formattedText, it was failing. I've changed this to add a workaround, and documented why this is a bit unusual in the readme.

I'm not able to read Spanish (let alone scan through quickly), but I think there are probably still some menu items that are not formatted as menus, especially when an item appears alone.

[tucotuco]

@MattBlissett @kcopas Can we close this issue?

[MattBlissett]

Yes, unless someone wants to go through the document and format every user interface item in the same way as the "la ▼ azul > Facetas > Faceta de texto" format. That might lead to too much formatting in the resulting document.

I think there are also some small inconsistencies about monospace text, e.g. above and below https://docs.gbif-uat.org/openrefine-guide/1.0/es/#img-fig-49 the | appears like that, and as ' | '.