[usage]How to add something to an exist section?

[wsdjeg]

@dbarnett Hi, I am author of SpaceVim, I want to use vimdoc generate doc for SpaceVim-layers. in this PR, wsdjeg/SpaceVim#127 , I define a Layers section in autoload/SpaceVim/layers.vim, and all the layers is in autoload/SpaceVim/layers/, for example autoload/SpaceVim/layers/lang/php.vim is lang#php layer. and the doc for this layer is in this vim script, But I want to append the doc of this layer to the end of section Layers, and make the doc looks like:

LAYERS                                                       *SpaceVim-layers*

       SpaceVim support many kinds of layers, in each layer contains 
  some plugins and config. here is the list of layers supported by 
  SpaceVim.
  
  lang#php :
              this layer is for php development, and it provide auto 
         codo completion, and syntax check, and jump to the definition
         location.
      
         requirement:
              PHP 5.3+
              PCNTL Extension
              Msgpack 0.5.7+(for NeoVim) Extension or JSON(for Vim 7.4+) Extension
              Composer Project

[dbarnett]

My suggestion would be to just keep those docs in the one file as a workaround for now. I've done similar in my plugins. Or you could try individual sections for "layers-php", "layers-python", etc. and see if that suits your needs better.

It's not a bad feature request, but it would definitely take a major effort to modify vimdoc to support it, and also suggests further questions about how to support control for the ordering if users ask for that.

[wsdjeg]

@dbarnett thanks for quick reply.

1. why I need split doc into different vim file?
   in the feature, SpaceVim will have too many layers, and each layer has it's own intro config etc. it will be easy for me to manager each layer's doc.

2. individual sections.
   yeah, nice idea, I will try to do it.

3. further questions.
   yeah, if doc can be append to the end of an exist section, it will be very hard to handle the order of the context.

thanks!

[wsdjeg]

@dbarnett
hi, I just try to use individual sections, but I have too many layers, I must add all the id of each section to @order, and all of them must be in oneline.
you can see my PR wsdjeg/SpaceVim#132 , now the line https://github.com/SpaceVim/SpaceVim/blob/update_doc/autoload/SpaceVim.vim#L5 has long weight then 80.

[dbarnett]

Yeah, I didn't expect it to work especially well. The @order problem is especially annoying.

I have too many competing priorities right now and don't be able to work on vimdoc features any time soon. I'll see if I can get any of my colleagues interested in helping though.

Anyway, if it was me, I'd go with the workaround of putting the docs for all layers in one file for now to have better control over the generated output.

[wsdjeg]

can I use @subsection?

[dbarnett]

Yeah, but I thought that only worked within the block for the section itself. Try it and see if it helps.

[wsdjeg]

I have tried, but it can not update contents menu;
I want to get:

CONTENTS                                                   *SpaceVim-contents*
  1. Introduction.............................................|SpaceVim-intro|
  2. Configuration...........................................|SpaceVim-config|
  3. Functions............................................|SpaceVim-functions|
  4. Layers..................................................|SpaceVim-layers|
         1. lang-php..................................|SpaceVim-layer-lang-php|
         2. lang-c......................................|SpaceVim-layer-lang-c|
         3. autocomplete...........................|SpaceVim-later-autocomplete|

[martindemello]

how about a parent argument when declaring the section, for instance

" @section Layer_lang_c < Layers

which would both declare the section a subsection of Layers and remove it from consideration for the top-level @order tag

[wsdjeg]

Yeah, nice feature,and with this feature , wo have no need to add all section into order,but only the top one.

[martindemello]

okay, i have the feature working. let's decide on the syntax before i send a pull request. some options:

" @section lang_c < Layers
" @section lang_c : @parent Layers
" @section lang_c @parent Layers

it should ideally be of the form <token> <parent name> and go at the end of the @section line for consistency with the existing syntax, but something like Layers::lang_c could be made to work too. "token" can consist of any combination of whitespace and fixed text/symbols, except for a comma which is already used for setting an explicit identifier

[dbarnett]

I think lang_c < Layers is as good as any of those options. Possibly a separate @parentsection would be more self-explanatory:

" @section lang-c, layer-lang-c
" @parentsection layers

I somehow have trouble reading right-major representations like B < A "B, child of A" whereas A > B makes perfect sense. Either way I think it won't be a common need and plugins that use it will get used to whatever convention.

[wsdjeg]

@dbarnett @martindemello thanks for these work, but how could we manager the order of subsection, or maybe it is just sort by name or id?

" @order intro layers
" @section Intro, intro
"  this is foo plugin
"  
"  
" @section Layers, layers
" @order layer-lang-c layer-lang-java
"  Layer contains some plugins and conifg.

"
"
" @section lang-c layer-lang-c
" @parentsection layers
"  

[martindemello]

@wsdjeg they are sorted by name; since @order is a global property it interacts badly with child sections (especially automatically collecting them), so vimdoc now checks that if a section has a parent-id it is not included in @order. if there's a real need for this i can add a separate @childorder to the section block, but it didn't seem like a large use case to me.

@dbarnett i'll take a look at adding a separate @parentsection directive; i had considered it briefly but it looked a lot more complicated to implement than an extra arg to @section. might as well get it right now, though.