Possible expansion of the User Guide?

[emyoulation]

I asked Perplexity to explain your the interface for ged2dot:

OK. Here's an explanation of how to use ged2dot.py, focusing on the command-line interface, and geared toward a beginner.

ged2dot.py is a tool that takes a GEDCOM file (a standard file format for genealogical data) as input and generates a Graphviz DOT file as output. The DOT file can then be processed by Graphviz (open-source graph visualization software) to create a visual family tree. Since there is no GUI, you must use the command line.

1. Prerequisites

• Python: You need Python 3 installed on your system. Most Linux distributions and macOS come with Python pre-installed. Windows users might need to download and install it from python.org.
• Graphviz: You also need Graphviz installed. This is a separate piece of software used to render the DOT file into an image (like a PNG or PDF). You can download it from graphviz.org or install it using your system's package manager (e.g., apt-get install graphviz on Debian/Ubuntu, brew install graphviz on macOS).
• ged2dot.py: Download the ged2dot.py script from the GitHub repository you linked to. Save it to a location on your computer where you can easily find it.

2. Basic Command-Line Usage

The most basic way to use ged2dot.py is like this:

python3 ged2dot.py -i input.ged -o output.dot

• python3: This tells your operating system to use the Python 3 interpreter to run the script.
• ged2dot.py: This is the name of the script you downloaded. Make sure your terminal is in the same directory where you saved the script, or provide the full path to the script.
• -i input.ged: This specifies the input GEDCOM file. Replace input.ged with the actual name of your GEDCOM file.
• -o output.dot: This specifies the output DOT file. Replace output.dot with the desired name for your DOT file.

After running this command, a file named output.dot will be created. This file contains the Graphviz DOT code representing your family tree.

3. Generating an Image from the DOT File

The .dot file by itself isn't an image. You need to use Graphviz to convert it into a viewable format. Here's how you can create a PNG image:

dot -Tpng output.dot -o family_tree.png

• dot: This is the Graphviz command-line tool.
• -Tpng: This specifies the output format as PNG. You can use other formats like pdf, jpg, svg, etc.
• output.dot: This is the input DOT file that ged2dot.py created.
• -o family_tree.png: This specifies the output file name. Replace family_tree.png with your desired file name.

This command will create a PNG image named family_tree.png that shows your family tree.

4. Important Options

ged2dot.py has several options to customize the output. Here are some of the most useful ones:

• -r or --rootfamily: Specifies the family ID to use as the root of the tree. By default, it uses "F1". If your tree isn't displaying correctly, you might need to find the main family ID in your GEDCOM file and use this option.

  python3 ged2dot.py -i input.ged -o output.dot -r F42

• -d or --familydepth: Controls how many generations are displayed in the tree. The default is 3. Increase this number to show more generations.

  python3 ged2dot.py -i input.ged -o output.dot -d 5

• --imagedir: Specifies the directory where images for individuals are stored. ged2dot.py looks for images based on the individual's name.

  python3 ged2dot.py -i input.ged -o output.dot --imagedir /path/to/images

• --nameorder: Determines the order of names (given name first or family name first). Can be "little" (default) or "big".

   python3 ged2dot.py -i input.ged -o output.dot --nameorder big

• --direction: Sets the direction of the family tree layout. Can be "topbottom", "leftright", or "both" (default).

  python3 ged2dot.py -i input.ged -o output.dot --direction topbottom

5. Example with More Options

Here's a more complex example that uses several options:

python3 ged2dot.py -i my_family.ged -o family.dot -r F12 -d 4 --imagedir images --nameorder big
dot -Tpdf family.dot -o family_tree.pdf

This will:

• Read the GEDCOM data from my_family.ged.
• Set the root family to "F12".
• Display 4 generations.
• Look for images in the "images" directory.
• Use "family name first" for names.
• Create a PDF file named family_tree.pdf.

6. Configuration File (Optional)

Instead of specifying all the options on the command line, you can use a configuration file. Create a file (e.g., ged2dot.conf) with the following structure:

[ged2dot]
input = my_family.ged
output = family.dot
rootfamily = F12
familydepth = 4
imagedir = images
nameorder = big

Then, run ged2dot.py with the -c option:

python3 ged2dot.py -c ged2dot.conf
dot -Tpdf family.dot -o family_tree.pdf

7. Troubleshooting

• "Family not found": Make sure the rootfamily ID is correct.
• No image is generated: Verify that Graphviz is installed correctly and that the dot command is in your system's PATH.
• Images not showing up: Double-check the imagedir path and the image file names. The script looks for images named after the individual, with common image extensions.
• Encoding Errors: If you get errors related to character encoding, ensure your GEDCOM file is encoded in UTF-8. You might need to re-save it with UTF-8 encoding using a text editor.

By following these steps, you should be able to use ged2dot.py to create visual representations of your family tree from your GEDCOM data. Remember to consult the ged2dot.py script itself (especially the comments) for more advanced options and details.

Citations:
[1] https://github.com/vmiklos/ged2dot/blob/master/ged2dot.py

[vmiklos]

The guide/ subdir has the docs, https://vmiklos.hu/ged2dot/usage.html is the rendered result of that. Can you submit a PR to improve it based on the above? Please make sure to actually verify everything AI said if it's actually true. Thanks.

[emyoulation]

I leveraged the AI to evaluate your module and write docs because, after skimming the various README.md files, I never found the usage.html file. Nor was there a clear statement whether the UI was graphical or command line.

Perhaps a link to it should be in "usage information" mention in the ged2dot Repository README.md ? The linked "User Guide" should ALSO have a link to the "usage.html"

from the https://github.com/vmiklos/ged2dot/blob/master/README.md :
"Check out the user guide for a list of features and installation and usage information."

The User Guide also lacks the promised "feature list" and "installation" detail.

[vmiklos]

Duplication is bad, so the README.md is a minimal one, and the actual documentation is a guide, with several chapters. One of them is the usage one. I don't want to list all chapters in README.md, because that would be again duplication.

Perhaps would it be useful to link usage.html in the README.md directly (because that's the most important chapter; instead of index.html) and then improve guide/src/usage.md if there is something missing there?

Edit: forgot to add:

The User Guide also lacks the promised "feature list" and "installation" detail.

http://vmiklos.hu/ged2dot/installation.html covers the install part.

For the feature list: yes, that's something you could probably add in guide/src/README.md, after the release date, before the "description" part; something like a "notable features" enumeration with a couple of bullet points. Care to submit a PR to do that?