btool
A parser/converter/transpiler for .bib files
btool Documentation

Software-Engineering-Assignment
summer semester 2020
BiB-Parser-Tool

TU-Chemnitz
Faculty of Computer Science
Professorship of Software Engineering

Project Status :octocat:

Builds :construction_worker: and Deployments :rocket:

Netlify Status Build Status

Code-Quality :art::nail_care:

Quality Gate Status Technical Debt Bugs Reliability Rating Maintainability Rating

Table of contents

Project-Description :pencil:

A Tool to process .bib-Files like:

@inproceedings{someID,
author = {Author A and Author B},
title = {{Very, very fancy title}},
booktitle = {A very serious collection of fancy stuff},
year = {2013},
pages = {1--18},
month = Feb,
publisher = {E-Corp},
}
@article{someID+42,
author = {Author C},
title = {{Is this a even more fancy title?}},
booktitle = {Greatest collection of knowlage ever},
year = {2019},
pages = {154--164},
month = May,
publisher = {Anonymous},
url = {https://www.anons.com/publications/docs/reallyfancy.pdf},
file = {reallyfancy.pdf}
}
...

Takes the name of a style (article, inproceedings, book, etc.), a collection of .bib-Files and a Property (title, author, year, etc.) to sort after, and produces a nicely formatted HTML-File with an overview over all the Publications in the given files matching the given style, ordered by the given ordering.
The Tool uses a JSON-File with rules containing names of known styles and their required and optional fields. :wrench:
The rule-table is easily editable and adding styles or fields will be a breeze. :sparkles:

Installation :rocket:

Prerequisites :seedling:

Boost-Library

Boost with a minimum version of 1.50
Follow the official boost instructions for linux/mac or windows to install and compile it on your machine.

CMake

CMake with a minimum version of 3.15 Follow the official cmake instructions to get yourself a running version of cmake.

Build :construction_worker:

  1. Clone the Repo and Submodules:

    ```bash $ git clone –recursive git@g.nosp@m.ithu.nosp@m.b.com:timkante/btool.git ```

  2. cd into the project:

    ```bash $ cd btool ```

  3. Create a build directory and cd into it:

    ```bash $ mkdir build && cd build ```

  4. Run the CMake target:

    ```bash $ cmake .. ```

  5. Build a target:

    5.1. For building the Tests:

    ```bash $ make btoolTest ```

    5.2. For building the Executable:

    ```bash $ make btool ```

  6. Run a target:

    6.1. For running the Tests:

    ```bash $ ./test/btoolTest ```

    6.2. For running the Executable:

    ```bash $ ./btool <YOUR_ARGUMENTS> ```

Alternative:

Get the executable for your Operating-System from the latest release, rename it to btool and hack away!

Usage :sparkles:

Basic program options:

  • -h [ --help ] print usage message
  • -o [ --output ] arg (="stdout") pathname for output (default is stdout)
  • -t [ --table ] arg full pathname of translation-table (can be used for extensive filtering)
  • -i [ --input ] arg file(s) to handle
  • -H [ --html ] set output-type to html
  • -X [ --xml ] set output-type to xml
  • -f [ --filter ] arg filter output for a style-name(s)
  • -s [ --sort ] arg sort output for a field

Usage constraints:

  • Only one output-type can be selected (--html or --xml), if no type is given, plain-text will be used
  • Generating output always requires one or more files/directories as input (--input)

Examples:

  • Show help message
    btool --help
  • Generating a HTML page from a given directory of .bib-files, sorted by author, filtered by translation-table, outputting it to ./index.html
    btool -t ./tables/mytable.json -i ./files --html -s author -o index.html
  • Print results from a given set of of .bib-files, sorted by author, filtered for articles and books, to stdout
    btool -i file1.bib file2.bib ./someMoreFiles -s author -f article booky

Using a translation-table:

If you want to do more complex filtering of elements, not only filtering for styles, maybe using a translation-table can help you.
Providing the Parser such a table, will make it filter for them.
It will only generate Elements that match the constraints given by the table.
So you have the ability to filter for styles with necessary fields and optional fields, Elements that don't have all necessary fields, or fields that are not necessary or optional, will get stripped off.
You can combine translation-table filtering with the --filter-option if you want to.

The translation-table has to be of the following (JSON) format:

type Table = {
styles: Constraint[];
}
type Constraint = {
name: String;
requiredFields: String[];
optionalFields: String[];
}

Here's an example:

{
"styles": [
{
"name": "article",
"requiredFields": [
"author",
"title",
"year",
"journal"
],
"optionalFields": [
"volume",
"number",
"pages",
"month",
"note"
]
},
{
"name": "book",
"requiredFields": [
"author",
"title",
"year",
"publisher"
],
"optionalFields": [
"volume",
"series",
"address",
"edition",
"month",
"note",
"isbn"
]
},
{
"name": "proceedings",
"requiredFields": [
"title",
"year"
],
"optionalFields": [
"volume",
"pages",
"address",
"edition",
"editor",
"month",
"note",
"organization",
"publisher"
]
}
]
}

Also see even bigger example.

Built with :heart: and

technology purpose
C++ speed
Travis-CI CI/CD
SonarQube/SonarCloud code-quality
CMake builds
Netlify documentation
GitHub version-control
googletest testing
Markdown non-code-documentation
Bootstrap HTML-Beautification
Doxygen documentation
spdlog logging
CTML HTML-Generation

Team :busts_in_silhouette:

Group-Members of Group 1:

  • Valeri Fitz (Project-Manager)
  • Kevin Diex
  • Saskia Heinrich
  • Tim Kante
  • Rashid Katamesh
  • Tom Seidel
  • Martin Zeidler

Milestones :triangular_flag_on_post:

Milestone 1 - KW 18
Milestone 2 - KW 19
Milestone 3 - KW 20
Milestone 4 - KW 21

Reports :pencil:

Report - KW 22
Report - KW 23
Report - KW 24
Report - KW 25
Report - KW 26
Report - KW 27
Report - KW 28
Report - KW 29

Required tasks :pencil:

Links :link:

For the current CI-Status/Report TravisCI
For Code-Analysis: SonarCloud
Documentation: Netlify
Presentation-slides: Netlify