User Guide

[danielecook]

Is there a user guide / documentation for htslib?

[jmarshall]

There is at present nothing beyond the (rather incomplete) API documentation inline in the header files.

(And what can be gleaned by considering the samtools and bcftools code as "sample code".)

[danielecook]

Thanks. I'll see what I can pick up.

[imgag]

I started using htslib to read/manipulate BAM files a few days ago and I second that there should be more documentation.

I can see that this is boring work and that documentation often diverges from the code, which is why in-code documentation has its advantages. However, the in-code documentation is often incomplete or completely missing (at least for the BAM part). Thus, I advocate for some example programs that read/write data to illustrate the most common use-cases. The example programs would be buildable/testable, so it's easy to keep them up-to-date.

For BAM files I would have hoped for these examples:

• read and print the file header and alignments
• manipulate the file header and alignments (including bases, qualities, CIGAR, ...)

[rulixxx]

Started using htslib myself some months ago and still find it difficult to find usage of some parts of it. It makes development more time consuming and error prone.

[valeriuo]

@rulixxx We are quite aware of this aspect and we are planning to invest more resources in the documentation and the user guide. In the meantime, can you describe your use case and see how we can assist you?
You can use [email protected], if you don't want to post it here.

[rulixxx]

Yes I was aware that this is a common complaint of users. I just wanted to add my grain of sand to addressing the issue (not just complain and forget about it). Thanks for your offer Valeriu. Thus far I have been able to get by looking at examples, header files and generated pages. My most recent problem was hunting down the return codes for several functions from htslib in order to harden a piece of code. I had to jump from headers to various documents in order to get the full picture for each function (not really sure Im looking at the most adequate/ updated source in the web). I just thought it would save time having all of it in one place with a simple navigation inferface...

…

________________________________ From: Valeriu Ohan <[email protected]> Sent: Tuesday, December 8, 2020 4:08 PM To: samtools/htslib <[email protected]> Cc: Raul Alcantara <[email protected]>; Mention <[email protected]> Subject: Re: [samtools/htslib] User Guide (#114) @rulixxx<https://github.com/rulixxx> We are quite aware of this aspect and we are planning to invest more resources in the documentation and the user guide. In the meantime, can you describe your use case and see how we can assist you? You can use [email protected]<mailto:[email protected]>, if you don't want to post it here. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#114 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AEAAUCEM7KHFTXZKTNWXCNLSTY6NRANCNFSM4AR6DJ2A>.