You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Writing user-friendly documentation is important for every successful software
245
254
project. This is particularly true when writing documentation for users in the
@@ -255,11 +264,22 @@ of the README of the project), and the vim documentation can be autogenerated.
255
264
256
265
RATIONALE *panvimdoc-motivation-rationale*
257
266
258
-
1. **Simplicity**: Writing in Markdown is often more intuitive for developers. By converting from Markdown to vimdoc, authors can maintain the simplicity of Markdown while adhering to the vimdoc standards.
259
-
2. **Unified Documentation**: Plugin authors can write their documentation just once (such as in the project’s README) and automatically generate vim documentation, ensuring consistency and saving time.
260
-
3. **Preserving Vim Features**: Vimdoc isn’t just plain text; it supports syntax highlighting, tags, links, and careful formatting using whitespace. It’s essential to preserve these features when converting to ensure the quality and usefulness of the documentation. See <https://vimhelp.org/helphelp.txt.html#help-writing> or `@nanotree`’s project <https://github.com/nanotee/vimdoc-notes> for more information.
261
-
4. **Leveraging Pandoc**: Unlike existing solutions, this project leverages Pandoc’s wide range of features, including support for multiple Markdown flavors and easy-to-write custom filters in Lua.
262
-
5. **Interoperability**: The choice of Pandoc allows for enhanced flexibility, making it easier to extend functionality or even adapt the converter for other documentation formats in the future.
267
+
1. **Simplicity**: Writing in Markdown is often more intuitive for developers. By converting from
268
+
Markdown to vimdoc, authors can maintain the simplicity of Markdown while adhering to the vimdoc
269
+
standards.
270
+
2. **Unified Documentation**: Plugin authors can write their documentation just once (such as in the
271
+
project’s README) and automatically generate vim documentation, ensuring consistency and saving
272
+
time.
273
+
3. **Preserving Vim Features**: Vimdoc isn’t just plain text; it supports syntax highlighting, tags,
274
+
links, and careful formatting using whitespace. It’s essential to preserve these features when
275
+
converting to ensure the quality and usefulness of the documentation. See
276
+
<https://vimhelp.org/helphelp.txt.html#help-writing> or
277
+
`@nanotree`’s project <https://github.com/nanotee/vimdoc-notes> for more information.
278
+
4. **Leveraging Pandoc**: Unlike existing solutions, this project leverages Pandoc’s wide range of
279
+
features, including support for multiple Markdown flavors and easy-to-write custom filters in
280
+
Lua.
281
+
5. **Interoperability**: The choice of Pandoc allows for enhanced flexibility, making it easier to
282
+
extend functionality or even adapt the converter for other documentation formats in the future.
By offering a specification and reference implementation for converting Pandoc
296
316
Markdown to vimdoc, this project aims to reduce friction in the documentation
297
317
process for vim plugin authors.
298
318
299
319
Here are the specific goals that guide this project:
300
320
301
-
- **Readability**: The Markdown files must render correctly when presented as README files on platforms like GitHub, GitLab, or SourceHut.
302
-
- **Web-Friendly HTML**: If converted to HTML using Pandoc, the Markdown files must be web-friendly and render appropriately.
303
-
- **VimDoc Features**: The generated vim documentation must support essential features like links and tags.
304
-
- **Aesthetically Pleasing**: The vim documentation must not only be functional but also visually pleasing in both vim and plain text files. This includes the appropriate use of columns and spacing.
305
-
- **Guidelines**: While the format of built-in Vim documentation is a valuable reference, it is used as guidelines rather than strict rules.
321
+
- **Readability**: The Markdown files must render correctly when presented as README files on
322
+
platforms like GitHub, GitLab, or SourceHut.
323
+
- **Web-Friendly HTML**: If converted to HTML using Pandoc, the Markdown files must be web-friendly
324
+
and render appropriately.
325
+
- **VimDoc Features**: The generated vim documentation must support essential features like links
326
+
and tags.
327
+
- **Aesthetically Pleasing**: The vim documentation must not only be functional but also visually
328
+
pleasing in both vim and plain text files. This includes the appropriate use of columns and
329
+
spacing.
330
+
- **Guidelines**: While the format of built-in Vim documentation is a valuable reference, it is used
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments