Convert AsciiDoc to TSV

Why Convert AsciiDoc to TSV?

Converting AsciiDoc documents to TSV format enables you to extract tabular data from documentation into a format optimized for spreadsheet operations and data analysis. TSV (Tab-Separated Values) is particularly advantageous when your data contains commas, currency values, or other content that would require extensive quoting in CSV format. The tab delimiter provides cleaner, more reliable separation of fields.

AsciiDoc tables frequently contain structured data such as configuration parameters, test results, inventory lists, and financial figures. When this data includes commas (as in currency values like $1,000 or addresses), TSV avoids the quoting complexity that CSV introduces. TSV is also the native clipboard format used by spreadsheet applications, meaning you can paste TSV data directly into Excel or Google Sheets without import dialogs or parsing configuration.

The conversion process extracts table content from AsciiDoc documents, parsing the pipe-delimited table syntax and converting each row into tab-separated fields. Header rows are preserved, cell content is cleaned of AsciiDoc formatting markup, and the output is encoded as clean, parseable TSV. For documents with multiple tables, each table is extracted and converted independently, maintaining the logical separation of data sets.

TSV is the standard data format in bioinformatics, genomics, and many scientific computing workflows. Researchers who document their experimental data in AsciiDoc can convert tables to TSV for direct use with tools like BEDTools, SAMtools, and R statistical packages. The format is also widely used in data engineering pipelines where tab-delimited files serve as efficient intermediate data representations.

Key Benefits of Converting AsciiDoc to TSV:

• Comma-Safe: No escaping needed for data containing commas or currency values
• Clipboard Ready: Direct paste into Excel and Google Sheets
• Scientific Data: Standard format for bioinformatics and research tools
• Data Extraction: Pull tabular data from documentation for analysis
• Fast Parsing: Simple delimiter makes processing extremely efficient
• Database Import: Load data into SQL databases and data warehouses
• Pipeline Integration: Use in automated data processing workflows

Practical Examples

Example 1: Financial Data Extraction

Input AsciiDoc file (sales-report.adoc):

= Annual Sales Report

.Revenue by Region
|===
|Region |Q1 Revenue |Q2 Revenue |Growth

|North America
|$1,250,000
|$1,380,000
|10.4%

|Europe
|$890,000
|$945,000
|6.2%

|Asia Pacific
|$670,000
|$780,000
|16.4%
|===

Output TSV file (sales-report.tsv):

Region	Q1 Revenue	Q2 Revenue	Growth
North America	$1,250,000	$1,380,000	10.4%
Europe	$890,000	$945,000	6.2%
Asia Pacific	$670,000	$780,000	16.4%

Example 2: Server Inventory Documentation

Input AsciiDoc file (servers.adoc):

== Infrastructure Inventory

.Production Servers
|===
|Hostname |IP Address |OS |CPU |RAM

|web-prod-01
|10.0.1.10
|Ubuntu 22.04
|8 cores
|32 GB

|db-prod-01
|10.0.1.20
|CentOS 9
|16 cores
|128 GB

|cache-prod-01
|10.0.1.30
|Alpine 3.18
|4 cores
|16 GB
|===

Output TSV file (servers.tsv):

Hostname	IP Address	OS	CPU	RAM
web-prod-01	10.0.1.10	Ubuntu 22.04	8 cores	32 GB
db-prod-01	10.0.1.20	CentOS 9	16 cores	128 GB
cache-prod-01	10.0.1.30	Alpine 3.18	4 cores	16 GB

Example 3: Gene Expression Data

Input AsciiDoc file (gene-data.adoc):

.Expression Levels
|===
|Gene ID |Gene Name |Sample A |Sample B |Fold Change

|ENSG00000139618
|BRCA2
|12.45
|8.92
|1.40

|ENSG00000141510
|TP53
|25.67
|31.20
|0.82

|ENSG00000171862
|PTEN
|9.88
|5.43
|1.82
|===

Output TSV file (gene-data.tsv):

Gene ID	Gene Name	Sample A	Sample B	Fold Change
ENSG00000139618	BRCA2	12.45	8.92	1.40
ENSG00000141510	TP53	25.67	31.20	0.82
ENSG00000171862	PTEN	9.88	5.43	1.82

Frequently Asked Questions (FAQ)

Q: What is TSV format?

A: TSV (Tab-Separated Values) is a plain text format for storing tabular data where columns are separated by tab characters (ASCII code 9). Each line represents a row, with tab characters delimiting the columns. TSV is an alternative to CSV that avoids quoting issues when data contains commas, making it simpler to parse and more reliable for certain data types.

Q: What is the difference between TSV and CSV?

A: The primary difference is the delimiter: TSV uses tab characters while CSV uses commas. TSV has fewer escaping requirements because tab characters rarely appear in data content, while commas are common in text, numbers (e.g., 1,000), and addresses. CSV has a formal specification (RFC 4180), while TSV has a registered IANA media type but no formal RFC.

Q: How are AsciiDoc tables converted to TSV?

A: The converter parses AsciiDoc table syntax (content between |=== markers) and extracts cell values. Each table row becomes a TSV row with tab characters separating cell contents. Header rows are preserved as the first row. AsciiDoc formatting within cells (bold, italic, etc.) is stripped, leaving only the text content for clean data output.

Q: Can I open TSV files in Excel?

A: Yes, Microsoft Excel fully supports TSV files. You can open them directly (Excel auto-detects the tab delimiter) or use the Import wizard for more control over column data types. You can also paste TSV data directly from the clipboard into Excel cells since tab-separated text is Excel's native clipboard format for multi-cell data.

Q: What happens to non-table content in my AsciiDoc file?

A: TSV is a data-only format designed for tabular content. Non-table elements such as headings, paragraphs, lists, code blocks, admonitions, and images from your AsciiDoc document are not included in the TSV output. The converter focuses specifically on extracting the structured tabular data that maps naturally to the TSV row-and-column format.

Q: Is TSV suitable for scientific data?

A: Absolutely! TSV is the standard format in many scientific fields, particularly bioinformatics and genomics. Tools like BEDTools, SAMtools, and BLAST use TSV for data exchange. R and Python pandas also handle TSV natively. The format's simplicity and lack of quoting ambiguity make it reliable for automated data processing in scientific pipelines.

Q: What encoding is used for the TSV output?

A: The converted TSV files use UTF-8 encoding, which supports all Unicode characters including international scripts, mathematical symbols, and special characters. This ensures compatibility with modern software while preserving any non-ASCII characters from your original AsciiDoc content. Most data analysis tools and spreadsheet applications handle UTF-8 encoded TSV files correctly.

Q: Can I import TSV data into a database?

A: Yes, all major database systems support TSV import. MySQL uses LOAD DATA INFILE with tab as the delimiter, PostgreSQL uses COPY with a tab delimiter specification, and SQLite supports .import with tab separation. GUI tools like pgAdmin, DBeaver, and MySQL Workbench also provide TSV import wizards for convenient data loading.