multiple language support

[wsdjeg]

Thanks for this project, and I hope vimdoc support multiple language at same time.

for example, when in a project, I want to generate two help file, doc/foo.txt and doc/foo.cnx.

and the src code :

""
" @section Introduction, intro
" Sources counter for vim and neovim.
"
" USAGE:
" >
"   :SourceCounter! vim md java html
" <

""
" @section 功能简介, intro
" @language cn
" 在 Vim 及 neovim 中进行代码数量统计。
"
" 使用：
" >
"   :SourceCounter! vim md java html
" <

let s:save_cpo = &cpoptions
set cpoptions&vim

""
" List lines count for specific [filetypes], or all supported filetypes.
"
" [!] forces desplay result in new tab.
command! -bang -nargs=* SourceCounter call SourceCounter#View('!' ==# '<bang>', <f-args>)

if !exists('g:source_counter_sort')
    ""
    " specific the sort type of result, 'lines'  or 'files', default is
    " 'files'.
    let g:source_counter_sort = 'files'
endif

let &cpoptions = s:save_cpo
unlet s:save_cpo

and the addon-info.json maybe also need to add a language section:

{
  "name": "SourceCounter.vim",
  "description": "Source counter in vim",
  "author": "wsdjeg",
  "language" : {
                              "default" : "txt",
                              "cn" : "cnx"
              }
}

the "default" : "txt" default key means generat default doc file doc/foo.txt based on all sections without @language tags.

[dbarnett]

Great idea!

I looked into how other doc comment tools like javadoc handle this, and they seem to avoid putting multiple languages inline in the files for the reasons I'd expect. Once you get a few languages added, (a) the clutter undermines the value of having readable doc comments in the code, and (b) developers who only know one of the languages wouldn't be able to keep translations up to date.

Would it work to have the doc comments in one primary language and integrate with a standard translation tool to pick up submitted translations from a separate source when generating the docs? I'd be fine with extending vimdoc with some supporting functionality/config.

[wsdjeg]

currently no translation tools can do this for complex doc, I think the easiest way is to add language tags，when the vimdoc generate doc, it can just skip the language which do not match the main config.

I just update https://github.com/google/vimdoc/issues/101#issue-358351762

[dbarnett]

For the sections with unique IDs at least they could be configured in some structured file or vimscript file that's never sourced by vim, like a myplugin/l10n/cn.vim file. I guess side-by-side translations in the main source files would be handy for bilingual plugin authors, but I'd hope we can have an answer that works reasonably for a dozen languages too.

What about the inline sections? They don't always have an obvious ID, but won't always detect multiple blocks.

For the config, do you have an example of other ways people might want to configure it?

[wsdjeg]

keep them in one file make it easier to maintained.

[dbarnett]

That's fair. I'm used to working with strings translated into 80 languages where inlining into a single vimscript file would get unmanageable, but realistically I guess no vim plugin is ever going to have docs professionally translated or more than 2 languages.

👍 to your suggestion to have @language directives that you could use inline to define content in specific languages, and then it could accept something like @language ALL to switch it back for things like code examples:

""
" @section 功能简介, intro
" Count the amount of code in vim and neovim.
"
" Usage:
" @language cn
" 在 Vim 及 neovim 中进行代码数量统计。
"
" 使用：
" @language ALL
" >
"   :SourceCounter! vim md java html
" <

[wsdjeg]

@dbarnett Thanks, I has just found new solution for this issue, so clossing. please see https://github.com/SpaceVim/SpaceVim/pull/4246

[dbarnett]

Interesting! Looks like it might make use of symlinks and subdirectories somehow to manage two versions?