bbl2bib

A Python tool to convert BBL (bibliography) files generated by BibTeX back into BIB format. This is useful when you have a compiled BBL file but need to reconstruct the original bibliography database.

Features

• 🔄 Automatic Entry Type Detection: Intelligently identifies entry types (article, book, inproceedings, etc.) based on content
• 📚 Smart Field Extraction: Extracts common fields like author, title, year, journal, pages, DOI, URL, etc.
• 🎨 Multiple Output Formats: Choose between standard, minimal, or full formatting styles
• 🚀 Batch Processing: Convert multiple BBL files at once
• 📝 Clean Output: Properly formatted BibTeX entries with correct field ordering
• 🔍 Robust Parsing: Handles various BBL formats and LaTeX commands

Installation

Requirements

• Python 3.7 or higher
• No external dependencies (uses only Python standard library)

Quick Setup (Recommended)

1. Clone the repository:

git clone https://github.com/yourusername/bbl2bib.git
cd bbl2bib

2. Run the setup script (creates virtual environment automatically):

chmod +x setup.sh
./setup.sh

3. Make the wrapper script executable:

chmod +x bbl2bib

Manual Setup

If you prefer to set up manually:

1. Clone the repository:

git clone https://github.com/yourusername/bbl2bib.git
cd bbl2bib

2. Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install the package:

pip install -e .

4. Make scripts executable (Unix/Mac only):

chmod +x bbl2bib.py bbl2bib

Usage

Using the Wrapper Script (Auto-activates Virtual Environment)

The easiest way to use bbl2bib is with the wrapper script that automatically handles the virtual environment:

./bbl2bib input.bbl

Manual Usage (With Virtual Environment)

If you prefer to manually activate the virtual environment:

source venv/bin/activate  # On Windows: venv\Scripts\activate
python bbl2bib.py input.bbl

Basic Usage

Convert a single BBL file to BIB:

./bbl2bib input.bbl
# or
python bbl2bib.py input.bbl  # if venv is already activated

This creates input.bib in the same directory.

Specify Output File

./bbl2bib input.bbl -o output.bib

Convert Multiple Files

./bbl2bib file1.bbl file2.bbl file3.bbl

Or use wildcards:

./bbl2bib *.bbl

Command Line Options

• -o, --output: Specify output file name (only for single input file)
• -v, --verbose: Enable verbose output for debugging
• --overwrite: Overwrite existing output files without confirmation
• --format: Choose output format style
  • standard (default): Well-formatted with proper indentation
  • minimal: Compact format without extra spacing
  • full: Include additional formatting and protection for special characters

Examples

# Convert with verbose output
./bbl2bib references.bbl --verbose

# Convert all BBL files in directory with minimal format
./bbl2bib *.bbl --format minimal --overwrite

# Convert with full formatting (protects capitalization)
./bbl2bib thesis.bbl --format full -o thesis_bibliography.bib

# If you've already activated the virtual environment manually:
python bbl2bib.py references.bbl --verbose

How It Works

1. Parsing: The tool reads the BBL file and identifies \bibitem entries
2. Analysis: Each entry is analyzed to determine:
   • Entry type (article, book, etc.)
   • Author names
   • Title
   • Publication details (journal, year, pages, etc.)
3. Extraction: Fields are extracted using pattern matching and heuristics
4. Formatting: Entries are formatted according to BibTeX standards
5. Output: Clean BIB file is generated with proper structure

Supported Entry Types

• @article - Journal articles
• @book - Books
• @inproceedings - Conference papers
• @incollection - Book chapters
• @phdthesis - PhD dissertations
• @mastersthesis - Master's theses
• @techreport - Technical reports
• @misc - Miscellaneous entries

Extracted Fields

The tool attempts to extract the following fields when present:

• Basic: author, title, year
• Publication: journal, booktitle, publisher
• Details: volume, number, pages, edition
• Identifiers: doi, isbn, url
• Location: address, school, institution
• Other: month, note, editor, series

Limitations

• The accuracy of conversion depends on the structure and formatting of the BBL file
• Some complex LaTeX formatting may not be perfectly preserved
• Custom bibliography styles might require manual adjustment of the output
• Field extraction relies on common patterns and may miss unconventional formatting

Project Structure

bbl2bib/
├── bbl2bib.py           # Main script
├── parser/
│   ├── __init__.py
│   └── bbl_parser.py    # BBL parsing logic
├── writer/
│   ├── __init__.py
│   └── bib_writer.py    # BIB file writer
├── utils/
│   ├── __init__.py
│   └── logger.py        # Logging utilities
├── examples/            # Example files
│   ├── sample.bbl
│   └── sample.bib
├── requirements.txt     # Python dependencies
└── README.md           # This file

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Development Setup

1. Clone the repository
2. Install development dependencies:

pip install pytest black flake8 mypy

3. Run tests:

pytest tests/

License

This project is licensed under the MIT License. See LICENSE file for details.

Troubleshooting

Common Issues

1. "No bibliography entries found"

   • Check that your BBL file contains \bibitem entries
   • Ensure the file encoding is UTF-8

2. Missing fields in output

   • The parser uses heuristics to extract fields
   • Manual adjustment may be needed for unusual formats

3. Incorrect entry types

   • Entry type detection is based on content patterns
   • You can manually edit the output BIB file to correct types

Getting Help

• Check the examples directory for sample input/output files
• Use --verbose flag for detailed parsing information
• Report issues on GitHub with sample BBL content