Skip to content

Commit 7f84a34

Browse files
docs: Add missing conference-acronym CLI command documentation [AI-assisted] (#209)
* docs: Add comprehensive conference-acronym CLI documentation [AI-assisted] Resolves issue #201 by adding complete documentation for the conference-acronym command group to the user guide. This addresses the critical gap where users could not discover or use the conference acronym expansion feature. Added documentation covers: - Conceptual overview of acronym expansion functionality - Purpose and benefits for bibliographic data processing - Complete command reference for all 5 subcommands (status, stats, list, clear, add) - Practical usage examples and workflows - Integration with assessment workflows - Reference to implementation at src/aletheia_probe/cli.py:325-467 Changes: - Updated table of contents to include new section - Added comprehensive "Conference Acronym Management" section - Positioned logically between Configuration and Data Sources sections * docs: Remove specific line numbers from implementation reference [AI-assisted] Addresses reviewer feedback to avoid stale line number references that will change as the codebase evolves. Now references the CLI file generally rather than specific line ranges. --------- Co-authored-by: florath-ai-assistant[bot] <Andreas.Florath@telekom.de>
1 parent c184d43 commit 7f84a34

File tree

1 file changed

+126
-3
lines changed

1 file changed

+126
-3
lines changed

docs/user-guide.md

Lines changed: 126 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,10 @@ This comprehensive guide covers all aspects of using the Journal Assessment Tool
1111
5. [Output Formats](#output-formats)
1212
6. [Understanding Results](#understanding-results)
1313
7. [Configuration](#configuration)
14-
8. [Data Sources](#data-sources)
15-
9. [Best Practices](#best-practices)
16-
10. [Troubleshooting](#troubleshooting)
14+
8. [Conference Acronym Management](#conference-acronym-management)
15+
9. [Data Sources](#data-sources)
16+
10. [Best Practices](#best-practices)
17+
11. [Troubleshooting](#troubleshooting)
1718

1819
## Overview
1920

@@ -490,6 +491,128 @@ backends:
490491
project_id: "your_project_id"
491492
```
492493
494+
## Conference Acronym Management
495+
496+
The conference acronym management feature helps expand conference abbreviations to their full names. This is particularly useful when processing bibliographic data where conferences may be referenced by common acronyms like "ICSE" (International Conference on Software Engineering) or "NIPS" (Neural Information Processing Systems).
497+
498+
### Concept
499+
500+
Conference acronyms are stored in a local database that maps short forms to their full conference names. The system automatically builds this mapping as it encounters conference data during journal assessments, and also allows manual management of acronym mappings.
501+
502+
### Purpose
503+
504+
- **Standardization**: Ensure consistent conference naming across bibliographic data
505+
- **Expansion**: Convert acronyms to full names for better readability and processing
506+
- **Data Quality**: Maintain a curated database of conference name mappings
507+
- **Automation**: Reduce manual effort in processing conference references
508+
509+
### Available Commands
510+
511+
The `aletheia-probe conference-acronym` command group provides the following subcommands:
512+
513+
#### Show Database Status
514+
515+
```bash
516+
# Check if acronym database has entries
517+
aletheia-probe conference-acronym status
518+
```
519+
520+
Displays basic information about the acronym database, including total count of stored mappings.
521+
522+
#### Display Statistics
523+
524+
```bash
525+
# Show detailed database statistics
526+
aletheia-probe conference-acronym stats
527+
```
528+
529+
Provides detailed statistics including:
530+
- Total number of acronym mappings
531+
- Most recently used acronym
532+
- Oldest entry in database
533+
- Usage timestamps
534+
535+
#### List All Mappings
536+
537+
```bash
538+
# List all acronym mappings
539+
aletheia-probe conference-acronym list
540+
541+
# List with pagination
542+
aletheia-probe conference-acronym list --limit 10
543+
aletheia-probe conference-acronym list --limit 20 --offset 50
544+
```
545+
546+
Shows all stored acronym mappings with details:
547+
- Acronym and full conference name
548+
- Source of the mapping (automatic detection vs. manual entry)
549+
- Creation and last-used timestamps
550+
- Normalized name for internal processing
551+
552+
#### Add Manual Mapping
553+
554+
```bash
555+
# Add a new acronym mapping
556+
aletheia-probe conference-acronym add "ICSE" "International Conference on Software Engineering"
557+
558+
# Add with custom source attribution
559+
aletheia-probe conference-acronym add "NIPS" "Neural Information Processing Systems" --source "manual-2024"
560+
```
561+
562+
Manually adds acronym mappings to the database. Useful for:
563+
- Pre-populating common acronyms
564+
- Correcting automatic mappings
565+
- Adding institution-specific acronyms
566+
567+
#### Clear Database
568+
569+
```bash
570+
# Clear all mappings (with confirmation prompt)
571+
aletheia-probe conference-acronym clear
572+
573+
# Clear without confirmation prompt
574+
aletheia-probe conference-acronym clear --confirm
575+
```
576+
577+
Removes all acronym mappings from the database. Use with caution as this action cannot be undone.
578+
579+
### Usage Examples
580+
581+
**Building an acronym database:**
582+
```bash
583+
# Start with empty database
584+
aletheia-probe conference-acronym status
585+
586+
# Add common computer science conferences
587+
aletheia-probe conference-acronym add "ICSE" "International Conference on Software Engineering"
588+
aletheia-probe conference-acronym add "FSE" "Foundations of Software Engineering"
589+
aletheia-probe conference-acronym add "ASE" "Automated Software Engineering"
590+
591+
# Check what was added
592+
aletheia-probe conference-acronym list --limit 5
593+
594+
# View statistics
595+
aletheia-probe conference-acronym stats
596+
```
597+
598+
**Managing existing mappings:**
599+
```bash
600+
# See current database size
601+
aletheia-probe conference-acronym status
602+
603+
# List recent entries
604+
aletheia-probe conference-acronym list --limit 10
605+
606+
# Clear outdated mappings if needed
607+
aletheia-probe conference-acronym clear --confirm
608+
```
609+
610+
### Integration with Assessment
611+
612+
The acronym database integrates automatically with journal assessment workflows. When processing bibliographic data, the tool uses stored mappings to expand conference acronyms, improving the accuracy of conference name matching and assessment.
613+
614+
For implementation details, see `src/aletheia_probe/cli.py`.
615+
493616
## Data Sources
494617

495618
### DOAJ (Directory of Open Access Journals)

0 commit comments

Comments
 (0)