Instrumente FOSS pentru editori leneși

Recent am avut ocazia să aflu ce înseamnă termenul „Tocilar Sniping”. Maëlle a subliniat o conversație pe rOpenSci Slack despre ceva numit Vale, destinat textului. Am văzut comentariul, dar sincer nu am înțeles despre ce este vorba până când Maëlle m-a întrebat dacă cred că ar fi util pentru editarea blogului…

… timpul trece…

Aproximativ trei zile mai târziu, cu greu am terminat niciuna dintre recenziile postărilor de blog pe care plănuiam să le fac. Am fost absorbit într-o groapă de iepure din Vale, reguli personalizate și depășiri.

Se pare că „Nerd Sniping” se referă la practica de a arunca probleme către tocilari care le distrag atenția de la ceea ce făceau.

Acestea fiind spuse, a fost o gaură glorioasă să cadă! A fost păcat că Maëlle m-a mai trage de două ori, întrebându-mă despre configurarea verificării ortografice în Positron și apoi întrebând dacă Panache m-ar ajuta cu traduceri.

Am fost destul de lent în sarcinile mele editoriale în acea săptămână! Dar am ieșit din scufundare cu o configurație editorială grozavă, care cu siguranță îmi va economisi timp în viitor.

Am editat mult de postări de pe blogul rOpenSci. Sunt mândru că îi ajut pe scriitori să-și transmită ideile cu claritate, fără a-și pierde propriul stil. Sunt un editor cu opinie, așa că încerc din greu să mă asigur că scriitorii înțeleg când sugestiile mele sunt doar părerea mea și când cred că există greșeli de stil sau de conținut care chiar trebuie remediate. De asemenea, sunt agitat în privința detaliilor, a consecvenței cu majusculele, a menținerii ideilor ordonate logic și a mă asigura că cititorii fără același fundal ar putea înțelege în continuare esenta postării.^.

Snipingul în timp util a lui Maëlle m-a ajutat să-mi finalizez colecția de instrumente pentru a ajuta la eficientizarea sarcinilor editoriale.

Toate aceste instrumente pot fi instalate și utilizate în moduri diferite. Ele sunt, de asemenea, puternice, cu multe personalizări și configurații posibile diferite. Aici, vă voi împărtăși cum folosesc aceste instrumente ca extensii în Positron pentru a facilita scrierea și editarea postărilor pentru blogul rOpenSci. Sperăm că acest lucru vă inspiră să explorați cum le puteți configura pentru a vă susține fluxurile de lucru! În plus, dacă sunteți interesat să vă configurați propriile instrumente, poate doriți să consultați această postare de blog despre „Toate modurile de a edita sau analiza în mod programatic documentele R Markdown / Quarto”.

Configurare generală

Pentru fiecare instrument, veți dori să instalați extensia Positron și apoi să vă configurați configurația. Configurațiile pot fi de obicei specificate la trei niveluri diferite:

• Utilizator: configurația dvs. la nivelul întregului sistem, care este modul în care doriți să funcționeze lucrurile în general în cadrul proiectelor. Fișierele de configurare ale utilizatorului sunt în general stocate undeva în directorul dvs. de acasă.
• Proiect: Configurare la nivel de proiect care înlocuiește configurarea utilizatorului dacă proiectul face lucrurile diferit. Aceste fișiere de configurare sunt stocate direct în proiect (cum ar fi roweb3pentru blogul rOpenSci).
• Fişier: Configurare fișier sau secțiune de fișiere care funcționează la o scară foarte locală. De obicei, această configurație este indicată de comentarii în fișier.

Mai precis, aici sunt (unele) locații/nume pentru fișierele de configurare și link-uri către secțiunile de documentație ale acestora pentru mai multe detalii.

Aceasta înseamnă că puteți avea reguli diferite pentru proiecte diferite și le puteți modifica după cum este necesar. În următoarele exemple, vă voi arăta cum fac acest lucru pentru postările de pe blogul rOpenSci.

Verificator ortografic cod (cSpell)

În primul rând este verificatorul meu ortografic, care probabil nu are nevoie de multe explicații. Cu toate acestea, este bine să folosiți un verificator ortografic care funcționează și pe cod. Folosesc extensia Code Spell Checker (cSpell) de la Street Side Software și am instalat extensiile de limbi individual:

• engleză canadiană ^{– Verificator ortografic cod}
• Franceză – Verificator ortografic cod
• Portugheză – Verificator ortografic cod
• Spaniolă – Verificator ortografic cod

Alternativ, puteți instala și cSpell Bundled Dictionaries în schimb.

Pentru a configura această extensie, am adăugat două tipuri de fișiere: un fișier de configurare la nivel de proiect și două dicționare de cuvinte pe care să le consideri „corecte”.

Fișierul de configurare la nivel de proiect, .cspell.jsonlistează limbile de utilizat pentru diferite fișiere (pentru a se asigura index.es.md fișierele trec prin verificatorul ortografic spaniol, în timp ce index.pt.md fișierele trec prin verificatorul ortografic portughez etc.). Include, de asemenea, o listă de globuri pentru căile fișierelor pe care le putem ignora (chiar nu sunt interesat de greșelile de ortografie din folderul .git), precum și indicarea către dicționare.

Aceste dicționare sunt create inițial de funcții din pachetul meu promoutils, un pachet R pentru toate fluxurile de lucru ale comunității mele rOpenSci.
wordlist_create() creează o listă de cuvinte bazată pe pachetele rOpenSci și pe numele autorilor, astfel încât acestea să nu declanșeze verificarea ortografică dacă nu sunt recunoscute.
wordlist_update() actualizează această listă cu nume noi după cum este necesar.

Păstrăm aceste dicționare în a .wordlists pliant. Numele sunt stocate în .wordlists/names.txt fișier și avem și un .wordlists/words.txt fișier care stochează cuvinte care sunt considerate corecte în contextul rOpenSci (cum ar fi „cazuri de utilizare”).

De asemenea, ar trebui să rețin că am o listă personală de cuvinte de utilizator stocate în setările mele de utilizator Positron, care listează cuvinte (cum ar fi numele meu!) pe care vreau să le consider corecte în toate proiectele.

Când scriem postări, putem, de asemenea, să suprascriem setările de limbă dintr-o postare folosind un comentariu special. De exemplu, dacă vrem să folosim engleza și portugheza pentru o postare, am putea adăuga <--- cSpell: language en,pt--> la document.

Putem include și cuvinte post-specifice de ignorat, ceea ce este util pentru acronime. De exemplu, dacă dorim să ignorăm acronimul CSCW am putea folosi în vârful unui post.

Problemele de verificare ortografică apar ca un avertisment în fereastra mea de text sau ca o listă sub „Probleme de verificare ortografică prin fișier” panoul inferior al ferestrei mele, astfel încât să le pot revizui, să le adaug la listele de cuvinte sau pur și simplu să le ignor mental.

Vale

Pentru textul liniștit (verificarea stil şi sens a cuvintelor) Folosesc extensia Vale VSCode de la chrischinchilla^{. Vale mă ajută să verific dacă regulile stilului de blog sunt respectate și oferă sugestii pentru alegeri alternative de cuvinte pentru a evita greșelile obișnuite (cum ar fi cuvinte sau expresii care ar putea fi derogatorii).}

Pentru a configura Vale am creat un fișier de configurare Vale specific proiectului .vale.ini ^{în depozitul roweb3. Îmi păstrez personalul .vale.ini fișier într-un folder de nivel superior care deține toate proiectele mele R. Pe lângă fișierul de configurare Vale, am creat și un folder de stiluri Vale în roweb3/.vale-styles. Aici sunt instalate regulile Vale dacă folosim reguli predefinite și unde pot pune reguli specifice rOpenSci pentru blog. Prima dată când folosești Vale, vei dori să alergi vale sync în terminal pentru a instala regulile standard, nepersonalizate. eu .gitignore toate regulile care sunt instalate, dar urmăriți și împingeți regulile personalizate.}

Vale este locul în care am făcut cele mai multe personalizări, în special cu blogul rOpenSci.

• Am adăugat o listă specifică de vocab de blog pentru a asigura valorificarea corectă a proiectelor rOpenSci și (să nu mai vorbim de „rOpenSci” 😉)
• Am dezactivat o mulțime de reguli specifice, care sunt puțin prea agresive pentru un blog care permite oamenilor să scrie ocazional și informal după cum le place (inclusiv folosind cuvinte precum „foarte” 😄).
• Am creat reguli personalizate pentru a modifica regulile existente
• Am creat reguli personalizate pentru a impune ghidul nostru de stil, cum ar fi folosirea majusculei pentru titluri pentru titlurile postărilor de blog^{caz de propoziție pentru subtitluri și folosind link-uri relative pentru paginile ropensci.org.}

Acesta este doar începutul! Îmi imaginez că, cu cât folosesc mai mult aceste reguli, cu atât voi face mai multe reglaje.

Problemele Vale sunt clasificate ca mesaje, avertismente sau erori și sunt evidențiate în fereastra de text ca o remediere rapidă și listate în panoul Probleme din fereastra de jos.

De asemenea, ar trebui să remarc că pentru toate regulile pe care le-am dezactivat, au mai rămas o mulțime de reguli cu opinii. Le păstrăm ca îndemnuri pentru a ne gândi la scrisul nostru, nu pentru că noi necesitate urmează-i!

Pompon

Pentru formatarea textului, folosesc extensia Panache de la jolars pentru a formata fișierele (R)markdown pentru blog. Aceasta este probabil cea mai mică cantitate de configurare, deoarece tot ce avem nevoie este un minim .panache.toml fișierul de configurare din depozitul roweb3. Cu toate acestea, acest fișier îl instruiește pe Panache să facă un lucru extraordinar pentru noi, în special pentru traducerile postărilor de blog multilingve:

(format)
wrap = "sentence"

Dacă configurați Positron să formateze la salvare, Panache împachetează automat text cu propoziție de fiecare dată când salvați fișierul. Aceasta înseamnă că atunci când o postare de blog este trimisă pentru o traducere de primă trecere folosind babeldown, traducerea revine destul de bine. În mod alternativ, dacă rupturile de rând sunt în mijlocul unei propoziții, traducerea poate deveni deformată, deoarece liniile sunt tratate ca secțiuni disjunse de text.

Pentru celelalte lucrări ale mele, o folosesc wrap = "reflow"setați în fișierul meu de configurare utilizator în ~/.config/panache/config.toml.

Solicitări de extragere GitHub

Pentru a revizui postările de pe blog, aduc PR-ul cu usethis::pr_fetch()și apoi deschideți fișierul postare de blog (R)md în Positron unul lângă altul cu previzualizarea html a postării în browserul meu web.

Apoi revizuiesc previzualizarea html și fac modificările direct în fișierul (R)md. Când am terminat, dau clic dreapta pe numele fișierului editat în Controlul sursei > Modificări și selectez Creare sugestii de solicitare de extragere.

O notă de precauție, consider că acest instrument este puțin confuz de utilizat pentru un PR care are deja o mulțime de comentarii. Comentariile pe care le face sunt uneori ascunse sau împărțite în moduri ciudate și este ușor să creați accidental duplicate. În aceste situații, uneori este mai ușor să faci sugestii într-un browser așa cum ai face în mod normal.

De ce atâtea unelte?

Fiecare dintre aceste instrumente îmi oferă o soluție specifică la o problemă. Există o oarecare suprapunere între ele; Vale putea să facă verificări ortografice, iar Panache să facă scame. Cu toate acestea, constat că, folosind instrumentele separat, pot realiza o configurare deosebit de detaliată și personalizată, care funcționează foarte bine cu blogul rOpenSci în special și cu munca mea în general.

Prin includerea fișierelor de configurare în depozitul roweb3, persoanele care folosesc și aceste instrumente vor folosi automat configurațiile pe care le-am configurat pentru blogul rOpenSci atunci când scriu o postare. De asemenea, intenționăm să adăugăm instrucțiuni despre cum să folosiți aceste instrumente în Ghidul blogului. Acest lucru ar trebui să le ofere scriitorilor de blog opțiunea de a folosi aceste instrumente dacă doresc.

Cu toate acestea, chiar dacă alți scriitori nu folosesc aceste instrumente, este totuși foarte util pentru mine să văd o listă de probleme potențiale de verificat la sfârșitul recenziei mele, fără a fi nevoie să-mi amintesc să le verific manual. Înseamnă că mă pot concentra mai mult pe revizuirea conținutului decât să-mi fac griji dacă este Ropensci sau rOpenSci 😄