{"id":31580998,"url":"https://github.com/open-technology-foundation/manpage","last_synced_at":"2026-05-11T07:21:23.615Z","repository":{"id":315987778,"uuid":"1061487558","full_name":"Open-Technology-Foundation/manpage","owner":"Open-Technology-Foundation","description":"Automatically generate and install UNIX man pages from README.md files using AI assistance.","archived":false,"fork":false,"pushed_at":"2025-09-22T03:06:36.000Z","size":40,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-22T03:33:29.636Z","etag":null,"topics":["bash","claude-code","manpage-generator"],"latest_commit_sha":null,"homepage":"https://yatti.id/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Open-Technology-Foundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T01:37:22.000Z","updated_at":"2025-09-22T03:06:39.000Z","dependencies_parsed_at":"2025-09-22T03:33:30.890Z","dependency_job_id":"257c5e03-4ab1-47e1-8453-9c68bb791975","html_url":"https://github.com/Open-Technology-Foundation/manpage","commit_stats":null,"previous_names":["open-technology-foundation/manpage"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Open-Technology-Foundation/manpage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fmanpage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fmanpage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fmanpage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fmanpage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Open-Technology-Foundation","download_url":"https://codeload.github.com/Open-Technology-Foundation/manpage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fmanpage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278526242,"owners_count":26001325,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","claude-code","manpage-generator"],"created_at":"2025-10-05T21:51:57.489Z","updated_at":"2025-10-05T21:52:03.368Z","avatar_url":"https://github.com/Open-Technology-Foundation.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# manpage\n\nAutomatically generates and installs professional man pages from README.md files using Claude AI assistance. Transform your existing documentation into properly formatted man pages with a single command.\n\n## Features\n\n- **Automatic Conversion**: Transforms README.md files into properly formatted troff/man pages using Claude AI\n- **Smart Installation**: Auto-detects installation context (user vs system-wide)\n- **Path Intelligence**: Automatically finds README.md files in command directories\n- **Standard Compliance**: Generates man pages following UNIX conventions with all standard sections\n- **Validation Support**: Includes comprehensive test suite for man page validation\n- **Error Recovery**: Robust error handling with informative messages\n- **Color Output**: Terminal-aware colored output for better readability\n\n## Installation\n\n### Quick Install (Recommended)\n\nInstall with a single command:\n\n```bash\n# System-wide installation (recommended)\ncurl -sSL https://raw.githubusercontent.com/Open-Technology-Foundation/manpage/main/install.sh | sudo bash\n\n# Or with wget\nwget -qO- https://raw.githubusercontent.com/Open-Technology-Foundation/manpage/main/install.sh | sudo bash\n\n# User-local installation (no sudo required)\ncurl -sSL https://raw.githubusercontent.com/Open-Technology-Foundation/manpage/main/install.sh | bash -s -- --user\n```\n\nThis will install:\n- The `manpage` command to `/usr/local/bin/` (or `~/.local/bin/` for user install)\n- Bash completion support to `/etc/bash_completion.d/`\n- The man page to `/usr/local/share/man/man1/`\n\n### Manual Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/Open-Technology-Foundation/manpage.git\ncd manpage\n\n# Make executable\nchmod +x manpage\n\n# Generate and install manpage's own man page (user-local)\n./manpage generate -i manpage\n\n# Or install system-wide\nsudo ./manpage generate -i manpage\n```\n\n### Uninstall\n\n```bash\n# System-wide uninstall\ncurl -sSL https://raw.githubusercontent.com/Open-Technology-Foundation/manpage/main/install.sh | sudo bash -s -- --uninstall\n\n# User-local uninstall\ncurl -sSL https://raw.githubusercontent.com/Open-Technology-Foundation/manpage/main/install.sh | bash -s -- --uninstall --user\n```\n\n## Quick Start\n\n```bash\n# Generate a man page for your script\nmanpage generate ./myscript\n\n# Generate and install in one command\nmanpage generate -i ./myscript\n\n# View the generated man page\nman myscript\n```\n\n## Usage\n\n```\nmanpage [options] \u003ccommand\u003e [arguments]\n```\n\n### Commands\n\n#### `generate` - Create man page from README.md\n\n```bash\nmanpage generate [-i|--install] \u003ccommand\u003e [\u003creadme\u003e]\n```\n\nConverts a README.md file to a properly formatted man page using Claude AI.\n\n**Arguments:**\n- `\u003ccommand\u003e`: Path to the command/script to document (required)\n- `\u003creadme\u003e`: Optional path to README.md file (defaults to command's directory)\n\n**Options:**\n- `-i, --install`: Install the man page immediately after generation\n\n**Behavior:**\n- Resolves full paths using `readlink -en` for reliability\n- Searches for README.md in the command's directory if not specified\n- Generates `.1` file in the same directory as the README\n- Validates output by checking for `.TH` directive\n- Exits with error if README.md not found or generation fails\n\n**Output:**\n- Creates `\u003ccommand\u003e.1` man page file\n- Displays success message with file path\n- Shows warnings for validation issues\n\n#### `install` - Install generated man page\n\n```bash\nmanpage install \u003ccommand\u003e\n```\n\nInstalls a previously generated man page to the appropriate directory.\n\n**Arguments:**\n- `\u003ccommand\u003e`: Path to the command whose man page to install\n\n**Installation Locations:**\n- **System-wide**: `/usr/local/share/man/man1/` (when running as root/sudo)\n- **User-local**: `~/.local/share/man/man1/` (for regular users)\n\n**Behavior:**\n- Auto-detects root/sudo context for installation type\n- Creates destination directories if needed\n- Updates man database (`mandb` or `makewhatis`)\n- Checks MANPATH configuration for user installations\n- Sets appropriate file permissions (644)\n\n### Global Options\n\n- `-h, --help`: Display help message and exit\n- `-v, --verbose`: Enable verbose output (default)\n- `-q, --quiet`: Disable verbose output\n- `-V, --version`: Show version information\n\n## Examples\n\n### Basic Usage\n\n```bash\n# Generate man page for a script in current directory\nmanpage generate ./myscript\n\n# Generate for a system command\nmanpage generate /usr/local/bin/mytool\n\n# Generate with explicit README location\nmanpage generate mytool ~/projects/mytool/docs/README.md\n\n# Generate and install immediately\nmanpage generate -i ./myscript\n```\n\n### Installation Examples\n\n```bash\n# Install for current user\nmanpage install ./myscript\n\n# Install system-wide\nsudo manpage install ./myscript\n\n# Quiet mode installation\nmanpage -q install ./myscript\n```\n\n### Advanced Examples\n\n```bash\n# Generate man page for a symlinked command\nmanpage generate $(which mycommand)\n\n# Generate from a specific branch's README\ngit show feature-branch:README.md \u003e /tmp/README.md\nmanpage generate mycommand /tmp/README.md\n\n# Batch processing\nfor script in scripts/*.sh; do\n  manpage generate -i \"$script\"\ndone\n```\n\n## How It Works\n\n### Architecture Overview\n\nThe `manpage` utility follows a clean, modular architecture:\n\n1. **Path Resolution Layer**\n   - Uses `readlink -en` for reliable path resolution\n   - Handles symlinks, relative paths, and special characters\n   - Falls back to alternative resolution methods if needed\n\n2. **README Discovery Engine**\n   - Intelligent search algorithm for locating README.md files\n   - Checks command directory first, then accepts explicit paths\n   - Validates file existence before processing\n\n3. **AI Conversion Pipeline**\n   - Constructs optimized prompts for Claude AI\n   - Specifies troff formatting directives and man page structure\n   - Includes all standard man page sections in proper order\n   - Handles complex markdown formatting conversions\n\n4. **Man Page Generation**\n   - Creates section 1 (user commands) man pages\n   - Validates output with `.TH` directive checks\n   - Stores generated files alongside source README\n   - Preserves original documentation structure\n\n5. **Smart Installation System**\n   - Auto-detects execution context (root/sudo vs user)\n   - Creates necessary directory structures\n   - Sets proper file permissions (644)\n   - Updates man database for immediate availability\n\n6. **Error Handling Framework**\n   - Comprehensive error checking at each step\n   - Informative error messages with exit codes\n   - Graceful fallback mechanisms\n   - Color-coded output for better visibility\n\n## Requirements\n\n### Core Dependencies\n\n- **claude**: Claude CLI tool (required for AI conversion)\n  ```bash\n  # Check if installed\n  which claude || echo \"Claude CLI not found\"\n  ```\n\n- **bash**: Version 4.0 or later\n  ```bash\n  # Check version\n  bash --version\n  ```\n\n- **Standard UNIX utilities**:\n  - `readlink` - Path resolution\n  - `grep` - Pattern matching\n  - `install` - File installation\n  - `mandb` or `makewhatis` - Man database updates\n\n### Optional Dependencies\n\n- **groff**: For rendering and testing man pages locally\n- **man**: For viewing generated man pages\n- **shellcheck**: For validating bash script syntax\n\n## Technical Details\n\n### Man Page Format\n\nGenerated man pages follow the troff/groff format with standard sections:\n\n1. **`.TH`** - Title header (name, section, date, version, manual)\n2. **NAME** - Command name and one-line description\n3. **SYNOPSIS** - Usage syntax with options\n4. **DESCRIPTION** - Detailed explanation of functionality\n5. **OPTIONS** - Command-line flags and parameters\n6. **EXAMPLES** - Practical usage demonstrations\n7. **EXIT STATUS** - Return codes and their meanings\n8. **ENVIRONMENT** - Environment variables used\n9. **FILES** - Configuration files and paths\n10. **NOTES** - Additional important information\n11. **BUGS** - Known issues or bug reporting\n12. **SEE ALSO** - Related commands and documentation\n13. **AUTHOR** - Creator and maintainer information\n14. **COPYRIGHT** - License and legal notices\n\n### Environment Configuration\n\n#### MANPATH Configuration\n\nFor user-local installations, ensure your MANPATH includes the local directory:\n\n```bash\n# Add to ~/.bashrc or ~/.zshrc\nexport MANPATH=\"$HOME/.local/share/man:$MANPATH\"\n\n# Verify MANPATH\nmanpath\n\n# Rebuild man database\nmandb\n```\n\n#### Claude CLI Configuration\n\nThe script uses Claude with specific options:\n- Model: Opus (configurable in script)\n- Flags: `-p --dangerously-skip-permissions`\n- Purpose: Bypasses interactive prompts for automation\n\n### File Locations\n\n- **Generated man pages**: `\u003creadme_dir\u003e/\u003ccommand\u003e.1`\n- **User installation**: `~/.local/share/man/man1/`\n- **System installation**: `/usr/local/share/man/man1/`\n- **Man database**: Updated via `mandb` or `makewhatis`\n\n## Troubleshooting\n\n### Common Issues\n\n#### \"claude command not found\"\n\nThe Claude CLI tool is required for AI conversion:\n\n```bash\n# Check if claude is installed\nwhich claude\n\n# Install instructions available at:\n# https://github.com/anthropics/claude-cli\n```\n\n#### \"Cannot find README.md\"\n\nThe script searches for README.md in the command's directory:\n\n```bash\n# Check if README exists\nls -la /path/to/command/README.md\n\n# Specify README path explicitly\nmanpage generate mycommand /custom/path/README.md\n```\n\n#### Man page not found after installation\n\nFor user installations, verify MANPATH configuration:\n\n```bash\n# Check current MANPATH\nmanpath\n\n# Add local man directory\necho 'export MANPATH=\"$HOME/.local/share/man:$MANPATH\"' \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n\n# Rebuild database\nmandb\n```\n\n#### Permission denied errors\n\n```bash\n# For system installation, use sudo\nsudo manpage install mycommand\n\n# Check file permissions\nls -la ~/.local/share/man/man1/\n```\n\n#### Invalid man page format\n\n```bash\n# Validate generated man page\ngroff -man -T ascii mycommand.1 \u003e /dev/null\n\n# Check for .TH directive\nhead -n 1 mycommand.1\n```\n\n### Debugging Tips\n\n```bash\n# Enable verbose mode for detailed output\nmanpage -v generate mycommand\n\n# Check generated file before installation\nless mycommand.1\n\n# Test man page rendering\nman -l mycommand.1\n\n# Verify installation location\nfind /usr/local/share/man ~/.local/share/man -name \"mycommand.1\" 2\u003e/dev/null\n```\n\n## Testing\n\n### Test Suite\n\nThe project includes a comprehensive test framework:\n\n```bash\n# Run complete test suite\n./test/test_manpage.sh\n\n# Run with verbose output\n./test/test_manpage.sh -v\n\n# Validate specific man page\n./test/validate_man.sh mycommand.1\n\n# Validate with detailed output\n./test/validate_man.sh -v mycommand.1\n```\n\n### Test Coverage\n\nThe test suite validates:\n\n- **Core Functionality**\n  - Man page generation from README\n  - Installation to user and system directories\n  - Path resolution and discovery\n\n- **Edge Cases**\n  - Paths with spaces and special characters\n  - Symlinks and relative paths\n  - Missing or invalid README files\n  - Non-existent commands\n\n- **Man Page Validation**\n  - Proper troff/groff syntax\n  - Required sections presence\n  - Format compliance\n  - Rendering without errors\n\n- **Error Handling**\n  - Missing dependencies\n  - Permission issues\n  - Invalid arguments\n  - Claude CLI failures\n\n### Running Tests\n\n```bash\n# Quick validation\nshellcheck -x manpage\n\n# Full test run\ncd test \u0026\u0026 ./test_manpage.sh\n\n# Specific test category\n./test/test_manpage.sh --category=generation\n```\n\n## Development\n\n### Project Structure\n\n```\nmanpage/\n├── manpage                # Main executable script\n├── README.md              # Project documentation (this file)\n├── LICENSE                # GPL-3 license file\n├── test/                  # Test suite directory\n│   ├── test_manpage.sh    # Comprehensive test runner\n│   ├── validate_man.sh    # Man page format validator\n│   └── fixtures/          # Test data and examples\n│       ├── sample.md      # Example README files\n│       └── expected/      # Expected output files\n└── manpage.1              # Generated man page for manpage itself\n```\n\n### Contributing\n\n#### Development Workflow\n\n1. **Fork and Clone**\n   ```bash\n   git clone https://github.com/yourusername/manpage.git\n   cd manpage\n   ```\n\n2. **Create Feature Branch**\n   ```bash\n   git checkout -b feature/your-feature\n   ```\n\n3. **Make Changes**\n   - Follow [BASH-CODING-STANDARD](https://github.com/Open-Technology-Foundation/bash-coding-standard)\n   - Maintain 2-space indentation\n   - Use `set -euo pipefail` for error handling\n   - Document new features in README\n\n4. **Test Thoroughly**\n   ```bash\n   # Syntax check\n   shellcheck -x manpage\n\n   # Run test suite\n   ./test/test_manpage.sh\n\n   # Test your changes\n   ./manpage generate -i testscript\n   ```\n\n5. **Submit Pull Request**\n   - Clear description of changes\n   - Reference any related issues\n   - Include test results\n\n#### Code Style Guidelines\n\n- **Bash Version**: Target bash 4.0+ compatibility\n- **Error Handling**: Use proper exit codes and error messages\n- **Functions**: Prefix internal functions with underscore\n- **Variables**: Use uppercase for globals, lowercase for locals\n- **Comments**: Document complex logic and non-obvious code\n\n#### Testing Guidelines\n\n- Add tests for new features\n- Update existing tests when modifying behavior\n- Ensure 100% pass rate before submitting PR\n- Include edge cases and error conditions\n\n### API Stability\n\nThe command-line interface is considered stable. Any breaking changes will:\n- Be documented in CHANGELOG\n- Increment major version number\n- Provide migration guide\n\n### Release Process\n\n1. Update version in script header\n2. Update README.md version reference\n3. Generate new man page\n4. Create git tag\n5. Push to repository\n\n## Support\n\n### Getting Help\n\n- **Documentation**: Read this README and generated man pages\n- **Issues**: [GitHub Issues](https://github.com/Open-Technology-Foundation/manpage/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/Open-Technology-Foundation/manpage/discussions)\n\n### Reporting Bugs\n\nWhen reporting issues, please include:\n- Operating system and version\n- Bash version (`bash --version`)\n- Claude CLI version\n- Complete error output\n- Steps to reproduce\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 (GPL-3).\n\nKey points:\n- Free to use, modify, and distribute\n- Source code must remain open\n- Modifications must use same license\n- No warranty provided\n\nSee [LICENSE](LICENSE) file for full details.\n\n## Credits\n\n### Author\n\nCreated and maintained by the [Indonesian Open Technology Foundation](https://yatti.id) for automating man page generation from existing documentation.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fmanpage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-technology-foundation%2Fmanpage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fmanpage/lists"}