ivoa-std / ivoatexdoc

This is the documentation for the IVOA authoring system ivoatex

See https://github.com/ivoa-std/ for how and where it is being used (in addition to authoring this document).

The released versions of this document are published on the IVOA document repository

The continuous integration also produces a current build of the document.

ivoatexdoc's Issues

lstlisting language formatting considered annoying

I generally find the language-specific formatting done by lstlisting more annoying than beneficial. For instance in sec 4.2 of the document, the following stanza:

\begin{lstlisting}[language=sh]
git checkout main
git pull origin main
git checkout -b branch-name-for-change
\end{lstlisting}

formats it all monospaced apart from the "for" which is in bold face. In section 2, this one:

\begin{lstlisting}[language=sh,basicstyle=\footnotesize]
git clone --recurse-submodules https://github.com/msdemlei/ivoatexDoc
cd ivoatexDoc
make biblio   # update the bibliography
make forcetex # make a PDF ignoring timestamps
make ivoatexDoc.html  # make an html document
make package # make a zipfile for IVOA submission
\end{lstlisting}

for some reason typesets "cd" in bold, and the rest of it in monospaced although it does the comments (after the #) in italic, which is arguably an improvement.

I find this (not very) cleverness distracting and would generally just prefer the whole thing monospaced including the comments. Arguably the benefits are greater for language settings other than sh, though e.g. it doesn't seem to be doing anything particularly smart for the archdiag example in sec 2.3.3 marked language=XML.

Is it just me? It's partly a matter of taste, and I can cope either way, but given we're recommending particular usage of the lstlisting package in ivoatexDoc I thought it was worth raising the question.

non existent ivoatex/startup.sh

Sec. 2.2.2 of ivoatexDoc mentions an ivoatex/startup.sh script that ivoatex submodule does not (any longer?) include.

Maybe the ivoatex/make-template.sh supersedes it?

process for migrating a repo to ivoa-std

Having performed a few of these and seeing what can happen, I still think there are some things to improve.

The doc-template can only really provide some default files that the original-repo does not: probably README.md and LICENSE and maybe a default workflow (have to check), which leads to two complications for the ivoa-std maintainer doing the migration:

1. if the original-repo already has these files a merge needs to be done
2. github supports and people are using either README.md and README.rst (yay, more markup langs); if you have both, the README.md seems to be the one github displays by default

So, that is a pain and probably makes the template mechanism offer so little that we should instead just require that the original-repo have a decent README and the LICENSE before going ahead with the migration. That also means that the author(s) have added the LICENSE themselves before hand, rather than it being implicitly added by the request to migrate, which I consider a good thing.

So, I propose to modify the migration process in this section to be something like:

1. check that original-repo has the minimum required files (README and LICENSE)
2. create repository ivoa-std/ using github import mechanism
3. setup github workflow (if not included in import)
4. setup branch protection rules
5. give WG team and editor the following privileges: maintainer role
6. notify WG and editor that migration is complete

Thoughts?