Warnings and Errors could link to the relevant section of the specification

[CholoTook]

Assuming each warning and error is a violation of the spec, you could link each of these to a specific part of the spec. This is how the python pep8 'validator' tool works. This would be a big help for noobs.

[jmmut]

I agree that it would be a great addition, but it's a huge work that we can't afford right now. We are probably doing dozens or even hundreds of checks. Moreover, the structure of the specs change across versions, and honestly, the constraints in the spec are not always in one single place, so we might need to link to several places, and if the spec organization is improved bit by bit, it will mean even more maintenace work here.

In general I would recommend searching the keywords in the spec and read all the parts that mention it.

What we can do is at least a link to the whole online pdf. Do you think that would be helpful?

[CholoTook]

Thanks JM, any link would be great, because people (noobs) won't know where the 'canonical' reference is (it can be hard to find).

I'd suggest that we petition the people in charge of the spec to formalise it to the point where specific items are stably identified. e.g. push the work onto them :-)

Do you know who I should pester?

Cheers,

On Tue, 5 Nov 2019 at 11:39, jmmut notifications@github.com wrote:

I agree that it would be a great addition, but it's a huge work that we can't afford right now. We are probably doing dozens or even hundreds of checks. Moreover, the structure of the specs change across versions, and honestly, the constraints in the spec are not always in one single place, so we might need to link to several places, and if the spec organization is improved bit by bit, it will mean even more maintenace work here.

In general I would recommend searching the keywords in the spec and read all the parts that mention it.

What we can do is at least a link to the whole online pdf. Do you think that would be helpful?

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/EBIvariation/vcf-validator/issues/195?email_source=notifications&email_token=ANKSZTRICXVZX6IH4SFNPD3QSFLPHA5CNFSM4JJBJSXKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEDCRMNA#issuecomment-549787188, or unsubscribe https://github.com/notifications/unsubscribe-auth/ANKSZTQ4VCAPQ2NZYTRAWPTQSFLPHANCNFSM4JJBJSXA .

[jmmut]

I became VCF spec maintainer this year, so you can pester me for things related to both the spec and the validator :) If you have any question or suggestion about the VCF spec (or SAM/BAM/CRAM) you can open an issue here https://github.com/samtools/hts-specs/ .

formalise it to the point where specific items are stably identified

I promise we are trying. This is hard. Different people understand things in different ways and it's hard to explain complicated things in concise ways, and making it easy for everyone to understand.

Right now there's not much concern about the problem of "keeping the same concepts in the same sections" because the problem of "describing everything completely in the proper place" is not solved, more important and contradicts the former.

I took notes to revisit in the future this "point to relevant section" feature, and will try to add some easy general links soon.

[CholoTook]

Many thanks for considering this.

I'll see if I can find time to see how the PEP8 people do it and report back.

Cheers, Dan.

On Tue, 5 Nov 2019 at 13:51, jmmut notifications@github.com wrote:

I became VCF spec maintainer this year, so you can pester me for things related to both the spec and the validator :) If you have any question or suggestion about the VCF spec (or SAM/BAM/CRAM) you can open an issue here https://github.com/samtools/hts-specs/ .

formalise it to the point where specific items are stably identified

I promise we are trying. This is hard. Different people understand things in different ways and it's hard to explain complicated things in concise ways, and making it easy for everyone to understand.

Right now there's not much concern about the problem of "keeping the same concepts in the same sections" because the problem of "describing everything completely in the proper place" is not solved, more important and contradicts the former.

I took notes to revisit in the future this "point to relevant section" feature, and will try to add some easy general links soon.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/EBIvariation/vcf-validator/issues/195?email_source=notifications&email_token=ANKSZTSCKQCOC6PDZUOAMDTQSF253A5CNFSM4JJBJSXKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEDC2RPI#issuecomment-549824701, or unsubscribe https://github.com/notifications/unsubscribe-auth/ANKSZTWFYNMSQGE74O33IB3QSF253ANCNFSM4JJBJSXA .

[jmmut]

That's interesting, I take note of it. Maybe they had an idea that makes this easier that we didn't think of.

[tcezard]

This is tracked internally in EVA-1730: closing the issue for now