Are there any specific caveats for add-ons documentation on the website?


Lukasz Golonka
 

Dear all,

From time to time there are discussions here about add-ons documentation
in markdown being rendered correctly on GitHub but wrongly after it is
committed into SVN and shown on the add-ons website. Until now I had no
access to Assembla and someone else had to update documentation of my
add-ons of my behalf, but since I can do it myself now I would like to
ask if there are any specific points which should be taken into account
when using markdown so that it renders correctly on the add-ons web page.

--
Regards
Lukasz


Noelia Ruiz
 

Hello: I"m not a translator, so I cannot provide the most reliable and complete answer. But I"ll start this thread saying what I try to do (despite mistakes):

1. Ensure that your document has the .mdwn extension in Assembla, though the extension on Github is .md.
2. Replace the heading level 1 úhich starts by a square symbol with the meta title tag, puting the title between double quotes (see a .mdwn file for examples).
3. Use asterisks followedb by space, not dash, for lists. Dashes are allowed on Github and on the website, but just in English. When the documentation is converted to .po files, using dashes doesn"t split the list in the desired items.
4. Use "reference" style for links, that is, include the corresponding urls at the botom of the file, with a blank line between urls (not sure if it"s needed, but maybe, and place a blank line at the bottom).
See examples. On Github we can include URLS between parentheses, but on the website we"ve always used reference style)..
5. Place the tags corresponding to the sections where the adddocumentation should appear before the references to the links, just before, with blank lines after the main content of the documentation and dev stable or dev tags, and a blank line after that and before the urls.
6. Try to use short paragraphs and lists, and headings of level 2 or 3 for a good structure and understandable documentation, avoiding a superlong or detailed changelog, since it should be translated and it"s better to focus in important things. This is just an additional recommendation and my own opinion.
Kind regards
Enviado desde mi iPhone

El 5 oct 2021, a las 17:05, Lukasz Golonka via groups.io <lukasz.golonka=mailbox.org@groups.io> escribió:

Dear all,

From time to time there are discussions here about add-ons documentation
in markdown being rendered correctly on GitHub but wrongly after it is
committed into SVN and shown on the add-ons website. Until now I had no
access to Assembla and someone else had to update documentation of my
add-ons of my behalf, but since I can do it myself now I would like to
ask if there are any specific points which should be taken into account
when using markdown so that it renders correctly on the add-ons web page.

--
Regards
Lukasz






José Manuel Delicado Alcolea
 

Hi,

Also, pay attention to nested lists. Put a blank line before the first sub-item and after the last one, and use four spaces to indent.

Regards.


El 06/10/2021 a las 6:32, Noelia Ruiz escribió:
Hello: I"m not a translator,  so I cannot provide the most reliable and complete answer. But I"ll start this thread saying what I try to do (despite mistakes):

1. Ensure that your document has the .mdwn extension in Assembla, though the extension on Github is .md.
2. Replace the heading level 1 úhich starts by a square symbol with the meta title tag, puting the title between double quotes (see a .mdwn file for examples).
3. Use asterisks followedb by space,  not dash, for lists. Dashes are allowed on Github and on the website, but just in English. When the documentation is converted to .po files,  using dashes doesn"t split the list in the desired items.
4. Use "reference" style for links, that is,  include the corresponding urls at the botom of the file, with a blank line between urls (not sure if it"s needed, but maybe, and place a blank line at the bottom).
See examples. On Github we can include URLS between parentheses, but on the website we"ve always used reference style)..
5. Place the tags corresponding to the sections where the adddocumentation should appear before the references to the links, just before, with blank lines after the main content of the documentation and dev stable or dev tags, and a blank line after that and before the urls.
6. Try to use short paragraphs and lists, and headings of level 2 or 3 for a good structure and understandable documentation,  avoiding a superlong or detailed changelog, since it should be translated and it"s better to focus in important things. This is just an additional recommendation and my own opinion.
Kind regards
Enviado desde mi iPhone

El 5 oct 2021, a las 17:05, Lukasz Golonka via groups.io <lukasz.golonka@...> escribió:

Dear all,

From time to time there are discussions here about add-ons documentation
in markdown being rendered correctly on GitHub but wrongly after it is
committed into SVN and shown on the add-ons website. Until now I had no
access to Assembla and someone else had to update documentation of my
add-ons of my behalf, but since I  can do it myself now I would like to
ask if there are any specific points which should be taken into account
when using markdown so that it renders correctly on the add-ons web page.

-- 
Regards
Lukasz










--

José Manuel Delicado Alcolea
Equipo de gestión web y desarrollo



Asociación Comunidad Hispanohablante de NVDA
- Tel.: (+34) 910 05 33 25 ext. 2001
- jm.delicado@...
- www.NVDA.es
- @nvda_es

***Este mensaje y sus adjuntos están dirigidos a su destinatario y pueden contener información exclusiva o confidencial. La utilización, copia o divulgación de los mismos por parte de alguien diferente a dicho destinatario no está permitida sin autorización. Si ha recibido este mensaje por error, le rogamos que lo comunique por esta misma vía y seguidamente lo destruya.***


Noelia Ruiz
 

And something that I wanted to mention: name the markdown file exactly
as the corresponding repo, needed for the translation system.


2021-10-06 10:40 GMT+02:00, José Manuel Delicado Alcolea via groups.io
<jm.delicado=nvda.es@groups.io>:

Hi,

Also, pay attention to nested lists. Put a blank line before the first
sub-item and after the last one, and use four spaces to indent.

Regards.


El 06/10/2021 a las 6:32, Noelia Ruiz escribió:
Hello: I"m not a translator, so I cannot provide the most reliable and
complete answer. But I"ll start this thread saying what I try to do
(despite mistakes):

1. Ensure that your document has the .mdwn extension in Assembla, though
the extension on Github is .md.
2. Replace the heading level 1 úhich starts by a square symbol with the
meta title tag, puting the title between double quotes (see a .mdwn file
for examples).
3. Use asterisks followedb by space, not dash, for lists. Dashes are
allowed on Github and on the website, but just in English. When the
documentation is converted to .po files, using dashes doesn"t split the
list in the desired items.
4. Use "reference" style for links, that is, include the corresponding
urls at the botom of the file, with a blank line between urls (not sure if
it"s needed, but maybe, and place a blank line at the bottom).
See examples. On Github we can include URLS between parentheses, but on
the website we"ve always used reference style)..
5. Place the tags corresponding to the sections where the adddocumentation
should appear before the references to the links, just before, with blank
lines after the main content of the documentation and dev stable or dev
tags, and a blank line after that and before the urls.
6. Try to use short paragraphs and lists, and headings of level 2 or 3 for
a good structure and understandable documentation, avoiding a superlong
or detailed changelog, since it should be translated and it"s better to
focus in important things. This is just an additional recommendation and
my own opinion.
Kind regards
Enviado desde mi iPhone

El 5 oct 2021, a las 17:05, Lukasz Golonka via
groups.io<lukasz.golonka=mailbox.org@groups.io> escribió:

Dear all,

From time to time there are discussions here about add-ons
documentation
in markdown being rendered correctly on GitHub but wrongly after it is
committed into SVN and shown on the add-ons website. Until now I had no
access to Assembla and someone else had to update documentation of my
add-ons of my behalf, but since I can do it myself now I would like to
ask if there are any specific points which should be taken into account
when using markdown so that it renders correctly on the add-ons web
page.

--
Regards
Lukasz







--

José Manuel Delicado Alcolea
Equipo de gestión web y desarrollo
Experto certificado en NVDA <https://certification.nvaccess.org>

Logotipo de la comunidad hispanohablante de NVDA
Asociación Comunidad Hispanohablante de NVDA
- Tel.: (+34) 910 05 33 25 ext. 2001 <tel:+34910053325,2001>
- jm.delicado@nvda.es
- www.NVDA.es <https://nvda.es>
- @nvda_es <https://twitter.com/nvda_es>

***Este mensaje y sus adjuntos están dirigidos a su destinatario y
pueden contener información exclusiva o confidencial. La utilización,
copia o divulgación de los mismos por parte de alguien diferente a dicho
destinatario no está permitida sin autorización. Si ha recibido este
mensaje por error, le rogamos que lo comunique por esta misma vía y
seguidamente lo destruya.***







Alberto Buffolino
 

Noelia Ruiz, il 06/10/2021 06.32, ha scritto:
4. Use "reference" style for links, that is, include the corresponding urls at the botom of the file, with a blank line between urls (not sure if it"s needed, but maybe, and place a blank line at the bottom).
Alberto:
Hi Noelia and all,
about reference style, in last years I always saw numeric reference, like:
[stable version][1]
but recently I'm adopting more often (due to my blog) a more confortable word/sequence reference, like:
[download stable][stable]
I think it's ok for translation system, so I report it here 🙂
Alberto


Noelia Ruiz
 

Great! Always happy to read your ideas. I suppose it's OK.

2021-10-06 12:20 GMT+02:00, Alberto Buffolino <a.buffolino@gmail.com>:

Noelia Ruiz, il 06/10/2021 06.32, ha scritto:
4. Use "reference" style for links, that is, include the corresponding
urls at the botom of the file, with a blank line between urls (not sure if
it"s needed, but maybe, and place a blank line at the bottom).
Alberto:
Hi Noelia and all,
about reference style, in last years I always saw numeric reference, like:
[stable version][1]
but recently I'm adopting more often (due to my blog) a more confortable
word/sequence reference, like:
[download stable][stable]
I think it's ok for translation system, so I report it here 🙂
Alberto






Cyrille
 

Generally,to test if a syntax is OK, the following 3 html files should be checked:
* English add-on's doc generated by the add-on scons command from the readme.md file
* English website's doc generated from the .mdwn 
* Translated website's doc generated from the mdwn and the .po file
Indeed, there may be slight differences in how the tools generate the html files.
I do not think that the translated add-on's doc needs to be checked since it is generated the same way as the website's translated doc.

I would also like to add some points and confirm other ones:

1. The reference style for links is nicer to read in the source (md) file but it is not mandatory

2. The reference style for too long links does not work (ikiwiki limitation). E.g: use the embedded link instead: "Click [here](http://www.here.com).". I do not know the max length for links allowed to be referenced; but you can see example of too long links in the Windows Magnifier (winMag) documentation.

3. Embedded lists
To be avoided when possible: risk of bad formatting that may lead to sublist items not split for translation.

Also, the following construct (cf winMag documentation) is not totally satisfying even if it is the best compromise:

===== beginning of markdown ======

Following is a list:

* A big item 1
  
    * sub-item 1
    * sub-item 2
  
  Another line still belonging to item 1

* Item 2

===== end of markdown ====== 

Other tries on this structure lead to sub-items not split.

HTH

Cyrille
 
De : "Noelia Ruiz"
A : nvda-addons@nvda-addons.groups.io
Envoyé: mercredi 6 Octobre 2021 12:26
Objet : Re: [nvda-addons] Are there any specific caveats for add-ons documentation on the website?
 
Great! Always happy to read your ideas. I suppose it's OK.

2021-10-06 12:20 GMT+02:00, Alberto Buffolino :
> Noelia Ruiz, il 06/10/2021 06.32, ha scritto:
>> 4. Use "reference" style for links, that is, include the corresponding
>> urls at the botom of the file, with a blank line between urls (not sure if
>> it"s needed, but maybe, and place a blank line at the bottom).
> Alberto:
> Hi Noelia and all,
> about reference style, in last years I always saw numeric reference, like:
> [stable version][1]
> but recently I'm adopting more often (due to my blog) a more confortable
> word/sequence reference, like:
> [download stable][stable]
> I think it's ok for translation system, so I report it here 🙂
> Alberto
>
>
>
>
>
>