search

felipet / ska_paper

Repo para el artículo de distribución de timing en SKA con la WR-ZEN
2 stars 0 forks source link

Añadir explicación de anotaciones #5

Closed felipet closed 7 years ago

felipet commented 7 years ago

Añadir a la Wiki como hacer anotaciones en el fichero de fuentes de latex

klyone commented 7 years ago

@felipet Este punto hay que aclararlo pronto porque me quiero poner a escribir y cuando nos revisemos de forma cruzada me gustaría saber cómo podemos poner anotaciones.

felipet commented 7 years ago

@klyone Estoy repensando el mejor método para hacer las revisiones y creo que sería más fácil utilizar otro método. Yo te propongo usar Master PDF porque te permite realizar anotaciones de manera bastante cómoda y desde Linux.

Puedes hacer lo mismo en Latex, pero no tengo claro como lo haríamos. Quiero decir, no tiene sentido añadir commits con correcciones porque puede que luego no se añadan a ningún sitio. Veo más normal pasar un pdf compilado cuando queramos que el otro revise y sobre ese pdf anotar, y de las anotaciones realizar las modificaciones en el Latex. No se como lo ves tu. ¿Ves alguna metodología medio decente para realizar las correcciones siguiendo la filosofia de commits?

klyone commented 7 years ago

@felipet Si no, otra cosa que podemos hacer es hacer una carpeta review en el repositorio y tener ahí un PDF con la última versión cuando queramos revisarlo. El problema de eso es que si por ejemplo yo añado comentarios en una versión A y tu modificas el Latex para una versión B no sé hasta que punto es facil mantener las anotaciones que había en A para que también estén en B. Es un tema un poco delicado...

Otra opción quizas es tener una rama de review y que los commits relativos a la revisión solo se hagan ahí.

En ambos casos siempre se puede utilizar los comentarios de Latex para marcar los aspectos que creemos que se tienen que revisar al estilo:

%% REVIEWED-BY: klyone COMMENT: Pienso que en este punto podrías explicar mejor A

klyone commented 7 years ago

@felipet Preguntando por el grupo de la Oficina de software libre me dicen esto:

Usuario 1: Comentarios en el fuente de latex no te valen (con %)? Es lo que suele hacer la gente. Como normalmente trabajas con el fuente directamente y ni compilas hasta el final, no tiene mucho sentido ponerlos en otro lado.

Usuario 2: Miguel, nosotros usamos comentarios de LaTeX y también los comentarios a los commit. También puedes usar comentarios sobre pull request. En resumen, múltiples formas. Otra opción es usar paquetes de LaTeX que te ponen comentarios en el texto. Nosotros tenemos esto en GeNeura (aunque la verdad usamos comentarios). geneura-papers

Usuario 3: Yo te recomiendo que utilices una página, overleaf.com, en la que escribes o editas texto en latex, lo puedes compartir con tus coautores(editarlo al mismo tiempo como en google drive) y una vez acabado lo subis a github.

Usuario 4: Eso usé yo para no dejarme cosas en el tfg.

Usuario 5: Puedes tambien, cuando subas tu revisión, abrir issues de las cosas que faltan o que tu compañero tiene que revisar.

Usuario 6: Aquí puedes encontrar una especie de guía de estilo para mensajes de commit. Me han pedido utilizarla en el proyecto al que contribuí, no se si su uso será más generalizado, pero es recomendable seguir un estándar. Si lo usas con GitHub, permite automatizar ciertas tareas, como cerrar issues cuando aprueban tu commit en un PR.

Después he preguntado sobre cómo se pueden hacer las anotaciones a un commit determinado y esta es la respuesta:

Usuario 7: Esto es que en el mismo commit, en la página de github, escribes abajo, igual que en los issues (Ejemplo).

Creo que con todo esto ya tenemos suficientes opciones para valorar, así que cuando le eches un ojo decidimos cuál es la forma más conveniente.

felipet commented 7 years ago

Vale resumiendo todo lo que tenemos. Dos vías veo yo:

  1. Cuando alguno tenga algo revisable (cosa que no es frecuente) genera un pdf, se lo pasa al otro y este lo revisa con una herramienta como Master PDF. El otro mira las correcciones y puede discutirlas por correo o similar.
  2. Cuando alguno quiera ser revisado, se hace una rama review de lo que lleve, le pone un issue al otro sobre la parte que desee revisar y el otro revisa utilizando: a) Latex (quizás sea más engorroso hacer las anotaciones aquí). Pero puedes seguir el flujo puro de git (hacer issues y discutirlos). b) Se compila la rama, y revisa sobre el pdf.

Como te veo con ganas de usar latex, podemos empezar usando 2a pero si vemos que al final conlleva más tiempo el proceso de revisión que la revisión en si misma yo optaría por el enfoque mixto de 2b. Si ves bien esa metodología, me encargo de hacer la página de la wiki definiendo que paquetes usamos para introducir mensajes y correcciones para no dar fallos de compilación entre ambos.

klyone commented 7 years ago

@felipet me parece bien, tambien se pueden hacer comentarios sobre un commit si es un cambio menor el que se requiere y no es una revisión completa.

felipet commented 7 years ago

Vale pues lo cierro y añado la página de la wiki.

klyone commented 7 years ago

@felipet Re-abro el issue: Hay que mirar el tema de que las anotaciones no señalan el texto al que anotan. Puede que esté relacionado con la plantilla de la revista.

Como vimos en el despacho, yo he probado ponerlo en una línea separado o entre medias del texto. Con el segundo enfoque lo que llegamos a ver es que ponía en cursiva la palabra siguiente al comando {k|f}cmdnote pero nada de subrayar ni de marcar de forma alguna.

klyone commented 7 years ago

@felipet ¿Has averiguado algo?

felipet commented 7 years ago

@klyone pues parece que no funciona. He probado con otras plantillas, con diferentes compiladores de latex y nada. Es raro porque eso antes iba. Voy a echar un vistazo a otros paquetes que había alternativos, porque esa funcionalidad es importante.

klyone commented 7 years ago

@felipet Vale, lo veo bien. A mí desde el primer momento no lo he visto funcionar nunca... Cuando sepas alguna cosa más me lo dices porque creo que es muy útil y es bastante más ágil de lo que parece inicialmente. Al menos, mientras yo he escrito, no me ha costado nada añadir las notas.

klyone commented 7 years ago

@felipet Entiendo que este tema se va a abordar en felipet/ska_paper#19 que es la tarea asignada a la migración del sistema de notas. Por tanto, cierro este issue.