Missing instructions on how to run mboxviewer

[samtuke]

The README doesn't seem to say actually how to run this app.

[zigm]

Hi,
If you mean how to start the application, I could possibly add a short statement how to start. You just double-left click on executable after unzipping the package. I recommend to review provided User Guide to learn how to start and run the application to use different features. What information would you like to see in the README?

[keithrbennett]

I strongly agree with @samtuke . I came to your project excited to try out your software, but have no idea how to run it. Instead, your Readme.markdown has a very long changelog that I had to scroll through to see if any instructions were below them.

I recommend removing the changelog from the readme, and inserting instructions instead, and not assuming any knowledge of which framework or language you are using.

For example, you said to double-left click on the executable, but did not say which file the executable is.

And on further inspection of your project, I see that the HELP.txt file has some better information, and that the executable is an .exe file. (However, I did not find that file in the git cloned project.) I assume this means that your project only runs on Windows, right? Then please say so prominently. I came to your project page from an AI search for a Mac-compatible mail viewer, and the AI was not able to figure out that the project is Windows-specific.

Thanks you for your time and expertise contribution to open source software, but if you have the time, please modify the readme to save future people like me from investing time in trying to figure it out for themselves.

[zigm]

Thank you both for taking time to raise the issue. I fully agree with the feedback and will address the issue in the next release.

I will rename README.txt to ReleaseNotes.md and update README.markdown.

On the Sourceforge (clone of GitHub project) , it is somewhat more clear that MBox Viewer is Windows specific.

Small note:

And on further inspection of your project, I see that the HELP.txt file has some better information, and that the executable is an .exe file. (However, I did not find that file in the git cloned project.)

The *.exe files are included in the release package only or when you clone the source code and build the project. Hopefully updated README will make this more clear.

In the past, several users asked to port MBox Viewer to other platforms. I investigated the request but unfortunately non trivial effort is required. There is no current plans to port MBox Virewer to other platforms but I plan to revisit the issue in the future.

[keithrbennett]

Thank you for being so open to feedback. There are some conventions that might be helpful for you and your readers. One is that ".md" is the conventional extension for markdown files. Another is that the main readme file is named README.md and other important markdown files in the top level project directory are named in all caps, such as RELEASE_NOTES.md (or CHANGELOG.md). You might want to look at other projects using your language/framework to see if there is a convention there. Here is a some general guidance from Google Gemini (the tool I'm using inserted "bard" but now it's "Gemini".

In your case you'd probably want a prominent section on building the software, and if it's very lengthy you could separate it out to another file, say 'BUILD_INSTRUCTIONS.md', and link to it in the README.md file. I've pasted instructions from Claude AI on linking to other markdown files at the end of this comment.

---

user: What is the best naming and content convention for markdown files in a Github project?

bard: Here's a breakdown of the best naming and content conventions for Markdown files in a GitHub project, combining proven practices and insights to optimize clarity and maintainability:

Naming Conventions

• Clear and descriptive: Choose names that accurately reflect the file's content (e.g., project_setup.md, database_schema.md).
• Conciseness counts: Keep file names relatively short for readability.
• Consistency is key: Use a consistent style across your project (e.g., snake_case new_feature_ideas.md or hyphen-separated contribution-guidelines.md).
• Prefixes for organization: Consider prefixes to group files by type or project area (e.g., docs_installation.md, api_reference.md).

Content Conventions

• README.md: The cornerstone of your project. Key sections should include:
  • Clear project title and brief description
  • Installation instructions
  • Usage examples
  • Contribution guidelines
  • Project roadmap (optional)
  • License information
• Structured headings: Use headings (H1, H2, H3, etc.) to organize content and improve navigation.
• Standard Markdown syntax: Adhere to widely-used Markdown syntax for formatting consistency.
• Images and diagrams: Visuals enhance explanations. Embed them using the standard Markdown image syntax.
• Code examples: Use code blocks (```) with language specifiers for clarity.
• Internal linking: Link to other relevant Markdown files within your project for easy reference ([Link Text](relative_path_to_file.md))

Additional Best Practices

• Centralized contribution file: Create a CONTRIBUTING.md file outlining how others can participate in your project. This is crucial for open-source projects.
• Changelog: Maintain a CHANGELOG.md to document project updates and release history.
• Version control: Use Git for version control to track changes and collaborate effectively.

Example Repository Structure

README.md   
CONTRIBUTING.md 
docs/
    installation.md
    usage_guide.md
    api_reference.md
src/       
tests/
LICENSE.md 

Important Considerations

• Target audience: Tailor your writing style and technical depth according to the intended readers.
• Tool Compatibility: If using specific Markdown editors or linters, ensure your conventions are compatible.

Why Follow Best Practices

Proper Markdown conventions in a GitHub project lead to the following benefits:

• Readability: Well-structured documents are easier to understand.
• Maintainability: Consistency makes updates and revisions smoother.
• Discoverability: Descriptive names and organization improve project navigation and searchability.
• Collaboration: Clear guidelines encourage participation within a project.

Let me know if you'd like to explore specific examples or adjust these conventions for a particular project type!

---

user: In Github markdown language, how do I link to another file in the same directory?

claude: In GitHub's Markdown language, you can link to another file in the same directory using relative file paths. The syntax for creating a link is as follows:

[Link Text](relative/path/to/file.md)

Here's an example of how to link to a file named other_file.md that's located in the same directory as the current file:

[Other File](other_file.md)

If the file you want to link to is located in a subdirectory, you need to specify the relative path from the current file's directory. For example, to link to a file named subdirectory/nested_file.md, you would use:

[Nested File](subdirectory/nested_file.md)

You can also use relative paths to link to files in parent directories by using ../ to move up one directory level. For instance, to link to a file named parent_file.md in the parent directory, you would use:

[Parent File](../parent_file.md)

Note that these relative paths work best for files within the same repository. If you want to link to a file in a different repository, you'll need to use the full URL instead of a relative path.

[zigm]

Hi Keith,

Thanks for great input. It will help to improve project structure and information presented to users.

As I mentioned I will revisit porting MBox Viewer to multiple platform, Not sure yet about what GUI development platform would work best for me. Such effort would create opportunity to re-architect parts of the current code (needed -:)) and to create better or more standard project structure and information from start.

Thanks,
Zbigniew

[keithrbennett]

Sounds ambitious! I'd recommend separating the re-architecting of your base product and the changing of the UI library into separate tasks, probably doing the re-architecting first so that you a) have the benefit of it even if you can't get to the GUI task, and b) the better code organization from the first task simplifies the second one.

I just researched cross platform GUI frameworks briefly, and for cross platform GUI applications in C++, QT seemed to be the best one, actually the only one ;) (see https://www.qt.io/download-open-source). Note their licensing requirements and make sure they are ok with you.

If you're open to changing your programming language, then there are also the following:

• Electron (JavaScript)
• React Native (JavaScript)
• Flutter (Dart)
• Java FX (Java or any language running on the JVM such as JRuby and Kotlin)

There are also text mode (terminal) full screen user interface libraries, if that fits your needs better.

[zigm]

I looked briefly Qt last year since it is c++ environment and I suppose widely used. Today I looked briefly the other platforms you listed. Electron and Flutter seem to be possible candidates for porting. The important dependency for me is solid support for Web Viewer. Automatic updates for WebView is strongly preferred for security reasons. Most of the platforms seems to have issue with this.

MBox Viewer relies on Microsoft legacy Web Browser DLls. They are still updated in the background by Microsoft. At some point MBox Vier would need to migrate to leverage WebView2, Microsoft version of Chrome WebView.

MBox Viewer has large dependency on Microsoft data structure such as CStrings, CArray, etc. You are correct that they would have to be replaced first with the standard C++ data structures whenever possible. Only recently I ported MBox Viewer to Unicode. MBox Viewer was created by Enea Mansutti in 2005. I took over the development in 2019 I believe.

I plan to play first with Qt and GUI. Installed the latest 6.6 version and installed Qt VS Tools extension for VS 2022. I am quite sure non trivial effort is required to port to Qt. Licensing is another issue I need to investigate. It looks like Qt has tons of dependencies on various licenses.

[keithrbennett]

@zigm I wish you well with this task. It sounds pretty massive to me.